EdjCase.ICP.ClientGenerator
6.2.0
See the version list below for details.
dotnet tool install --global EdjCase.ICP.ClientGenerator --version 6.2.0
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local EdjCase.ICP.ClientGenerator --version 6.2.0
#tool dotnet:?package=EdjCase.ICP.ClientGenerator&version=6.2.0
nuke :add-package EdjCase.ICP.ClientGenerator --version 6.2.0
Client Generator
- Library of generating C# client code from *.did files
- Nuget:
EdjCase.ICP.ClientGenerator
Usage (dotnet tool)
Install with dotnet tools
dotnet tool install -g EdjCase.ICP.ClientGenerator
Run tool
(First run only) Initialize config file and update generated file
candid-client-generator init ./
Creates candid-client.toml
file to update in specified directory
Example:
namespace = "My.Namespace"
output-directory = "./Clients"
no-folders = false
[[clients]]
name = "Dex"
type = "file"
file-path = "./ServiceDefinitionFiles/Dex.did"
[[clients]]
name = "Governance"
type = "canister"
canister-id = "rrkah-fqaaa-aaaaa-aaaaq-cai"
Generate clients
candid-client-generator ./
or
candid-client-generator gen ./
Config file options
Top Level:
namespace
- (Text) REQUIRED. The base namespace used in all C# files generated. Files generated in a sub-folder will have a more specific namespace to match. This namespace can be overidden per client.output-directory
- (Text) OPTIONAL. Directory to put all generated files. Each client will have a sub-folder within the output directory that will match the client name. If not specified, the working directory will be usedno-folders
- (Bool) OPTIONAL. If true, no sub-folders will be generated for the clients or the models within the clients. All generated files will be in a flat structure. Defaults to falseurl
- (Text) OPTIONAL. Sets the boundry node url to use for making calls to canisters on the IC. Can be set to a local developer instance/localhost. Defaults to 'https://ic0.app/'. This setting is only useful for clients of generation typecanister
feature-nullable
- (Bool) Optional. Sets whether to use the C# nullable feature when generating the client (likeobject?
). Defaults to truevariants-use-properties
- (Bool) Optional. If true, the generated variant classes will use properties instead of methods for data access. Defaults to falsekeep-candid-case
- (Bool) Optional. If true, the names of properties and methods will keep the raw candid name. Otherwise they will be converted to something prettier. Defaults to falseoverride-optional-value
- (Bool) Optional. If false, opt Candid types will be represented as OptionalValue<T>, otherwise will just use T? (where possible). Defaults to false. NOTE: this feature is not recommended for type and performance reasons and should be considered experimental
Client Level:
name
- (Text) REQUIRED. The name of the sub-folder put the client files and the prefix to the client class name.type
- (Text) REQUIRED. An enum value to indicate what type of client generation method to use. Each enum value also has associated configuration settings. Options:file
- Will create a client based on a service definition file (*.did
)file-path
- (Text) REQUIRED. The file path to the*.did
file to generate from
canister
- Creates a client based on a canister idcanister-id
- (Text) REQUIRED. The principal id of the canister to generate a client for
output-directory
- (Text) OPTIONAL. Directory to put all generated client files. Overrides the top leveloutput-directory
. NOTE: this does not create a sub-folder based on the client name like the top leveloutput-directory
doesno-folders
- (Bool) OPTIONAL. If true, no sub-folders will be generated for the client. All generated files will be in a flat structure. Defaults to false. Overrides the top levelno-folders
feature-nullable
- (Bool) Optional. Sets whether to use the C# nullable feature when generating the client (likeobject?
). Defaults to true. Overrides the top levelfeature-nullable
keep-candid-case
- (Bool) Optional. If true, the names of properties and methods will keep the raw candid name. Otherwise they will be converted to something prettier. Defaults to false. Overrides the top levelkeep-candid-case
override-optional-value
- (Bool) Optional. If false, opt Candid types will be represented as OptionalValue<T>, otherwise will just use T? (where possible). Defaults to false. NOTE: this feature is not recommended for type and performance reasons and should be considered experimental
Type Customization:
All Types
[clients.types.{CandidTypeId}]
{CandidTypeId}
is any named type in the candid definition
name
- Optional. (Text) Overrides the name of the C# type/alias generated
Record Types Options
[clients.types.{CandidTypeId}.fields.{CandidFieldId}]
{CandidFieldId}
is a record field in the record type{CandidTypeId}
Uses the same options as the top level
[clients.types.{CandidTypeId}]
section
Variant Types Options
representation
- Optional (Text) Sets what C# type should be generated. (Defaults to Dictionary if possible, otherwise a List)ClassWithMethods
- (Default) Uses a C# class with method accessorsClassWithProperties
- Uses a C# class with property accessors
[clients.types.{CandidTypeId}.fields.{CandidOptionId}]
{CandidOptionId}
is a variant option in the variant type{CandidTypeId}
Uses the same options as the top level
[clients.types.{CandidTypeId}]
section
Vec Types Options
representation
- Optional (Text) Sets what C# type should be generated. (Defaults to Dictionary if possible, otherwise a List)Array
- Uses a C# arrayDictionary
- (Default if applicable) Uses a C#Dictionary<TKey, TValue>
. Only works if thevec
contains arecord
with 2 unamed fields (tuple). The first will be the key, the second will be the valueList
- (Default if not Dictionary) Uses a C#List<T>
[clients.types.{CandidTypeId}.innerType]
Uses the same options as the top level
[clients.types.{CandidTypeId}]
section, butname
is not supported
Opt Types Options
[clients.types.{CandidTypeId}.innerType]
Uses the same options as the top level
[clients.types.{CandidTypeId}]
section, butname
is not supported
Type Customization Example:
[clients]
...
[clients.types.AccountIdentifier]
name = "AccountId"
[clients.types.AccountIdentifier.fields.hash]
name = "Hash"
representation = "Array"
[clients.types.Action.fields.RegisterKnownNeuron]
name = "RegisterNeuron" # Rename RegisterKnownNeuron -> RegisterNeuron
[clients.types.Action.fields.RegisterKnownNeuron.fields.id] # Update the type's field `id`
name = "ID" # Rename id -> ID
[clients.types.Action.fields.RegisterKnownNeuron.fields.id.innerType.fields.id] # Update the opt's inner record type's field `id`
name = "ID" # Rename id -> ID
Custom Client Generators via Code
Due to the complexity of different use cases, custom tweaks to the output of the client generators might be helpful. This process
can be handled with calling the ClientCodeGenerator
manually and using the .NET CSharpSyntaxRewriter
(tutorial can be found HERE)
var options = new ClientGenerationOptions(
name: "MyClient",
@namespace: "My.Namespace",
noFolders: false,
featureNullable: true,
keepCandidCase: false
);
ClientSyntax syntax = await ClientCodeGenerator.GenerateClientFromCanisterAsync(canisterId, options);
var rewriter = new MyCustomCSharpSyntaxRewriter();
syntax = syntax.Rewrite(rewriter);
(string clientFile, List<(string Name, string Contents)> typeFiles) = syntax.GenerateFileContents();
// Write string contents to files...
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
This package has no dependencies.
Version | Downloads | Last updated |
---|---|---|
7.0.0-pre.1 | 52 | 10/27/2024 |
6.2.1 | 129 | 10/23/2024 |
6.2.0 | 104 | 10/21/2024 |
6.1.2 | 156 | 4/30/2024 |
6.1.1 | 131 | 4/17/2024 |
6.1.0 | 175 | 4/15/2024 |
6.0.0 | 229 | 3/21/2024 |
5.1.0 | 239 | 1/25/2024 |
5.0.0 | 292 | 1/12/2024 |
5.0.0-pre.2 | 203 | 12/13/2023 |
5.0.0-pre.1 | 115 | 12/11/2023 |
4.1.0 | 475 | 11/10/2023 |
4.0.1 | 511 | 11/1/2023 |
4.0.0 | 452 | 10/12/2023 |
4.0.0-pre.10 | 156 | 10/10/2023 |
4.0.0-pre.9 | 141 | 10/10/2023 |
4.0.0-pre.8 | 151 | 10/9/2023 |
4.0.0-pre.7 | 134 | 10/9/2023 |
4.0.0-pre.6 | 174 | 10/9/2023 |
4.0.0-pre.5 | 170 | 10/8/2023 |
4.0.0-pre.4 | 161 | 10/6/2023 |
4.0.0-pre.3 | 130 | 10/5/2023 |
4.0.0-pre.2 | 138 | 9/27/2023 |
4.0.0-pre.1 | 153 | 9/25/2023 |
3.2.2 | 538 | 9/22/2023 |
3.2.1 | 514 | 9/22/2023 |
3.2.0 | 420 | 8/2/2023 |
3.1.5 | 543 | 9/27/2023 |
3.1.4 | 391 | 7/20/2023 |
3.1.3 | 313 | 6/12/2023 |
3.1.2 | 396 | 5/11/2023 |
3.1.1 | 383 | 5/9/2023 |
3.1.0 | 333 | 5/9/2023 |
3.0.1 | 251 | 5/2/2023 |
3.0.0 | 300 | 5/1/2023 |
3.0.0-beta.1 | 149 | 4/17/2023 |
2.3.9 | 226 | 5/1/2023 |
2.3.8 | 254 | 4/28/2023 |
2.3.7 | 250 | 4/28/2023 |
2.3.6 | 215 | 4/28/2023 |
2.3.5 | 240 | 4/27/2023 |
2.3.4 | 235 | 4/27/2023 |
2.3.3 | 238 | 4/26/2023 |
2.3.2 | 255 | 4/26/2023 |
2.3.1 | 276 | 4/26/2023 |
2.3.0 | 299 | 4/25/2023 |
2.2.10 | 242 | 4/24/2023 |
2.2.9 | 270 | 4/24/2023 |
2.2.8 | 253 | 4/24/2023 |
2.2.7 | 271 | 4/17/2023 |
2.2.6 | 307 | 4/12/2023 |
2.2.5 | 301 | 4/12/2023 |
2.2.4 | 293 | 4/11/2023 |
2.2.3 | 300 | 4/11/2023 |
2.2.2 | 320 | 4/7/2023 |
2.2.1 | 328 | 4/7/2023 |
2.2.0 | 318 | 4/6/2023 |
2.1.1 | 324 | 3/30/2023 |
2.1.0 | 349 | 3/23/2023 |
2.0.8 | 390 | 3/20/2023 |
2.0.7 | 325 | 3/12/2023 |
2.0.2 | 364 | 3/10/2023 |
2.0.1 | 351 | 3/10/2023 |
2.0.0 | 335 | 3/8/2023 |
2.0.0-beta.26 | 152 | 3/8/2023 |
2.0.0-beta.25 | 150 | 3/8/2023 |
2.0.0-beta.24 | 134 | 3/7/2023 |
2.0.0-beta.23 | 141 | 3/6/2023 |
2.0.0-beta.22 | 138 | 3/1/2023 |
2.0.0-beta.21 | 145 | 2/28/2023 |
2.0.0-beta.20 | 144 | 2/20/2023 |
2.0.0-beta.19 | 146 | 2/14/2023 |
2.0.0-beta.18 | 142 | 2/14/2023 |
2.0.0-beta.17 | 137 | 2/14/2023 |
2.0.0-beta.16 | 141 | 2/11/2023 |
2.0.0-beta.15 | 142 | 2/10/2023 |
2.0.0-beta.14 | 136 | 2/6/2023 |
2.0.0-beta.13 | 142 | 2/3/2023 |
2.0.0-beta.12 | 151 | 2/2/2023 |
2.0.0-beta.11 | 147 | 1/30/2023 |
2.0.0-beta.10 | 144 | 1/23/2023 |
2.0.0-beta.9 | 140 | 1/19/2023 |
2.0.0-beta.7 | 134 | 1/12/2023 |
2.0.0-beta.6 | 139 | 12/31/2022 |
2.0.0-beta.5 | 133 | 12/30/2022 |
2.0.0-beta.4 | 130 | 12/21/2022 |
2.0.0-beta.3 | 142 | 12/19/2022 |
2.0.0-beta.2 | 128 | 12/10/2022 |
2.0.0-beta.1 | 140 | 12/2/2022 |
1.2.1 | 443 | 11/29/2022 |
1.2.0 | 392 | 11/28/2022 |
1.1.0 | 404 | 11/28/2022 |
1.0.3 | 426 | 11/25/2022 |
1.0.2 | 546 | 6/8/2022 |
1.0.1 | 526 | 6/7/2022 |
0.0.1-beta.20 | 168 | 6/1/2022 |
0.0.1-beta.19 | 173 | 5/20/2022 |
0.0.1-beta.14 | 173 | 5/19/2022 |