EdjCase.ICP.ClientGenerator 6.1.2

dotnet tool install --global EdjCase.ICP.ClientGenerator --version 6.1.2                
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest # if you are setting up this repo
dotnet tool install --local EdjCase.ICP.ClientGenerator --version 6.1.2                
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=EdjCase.ICP.ClientGenerator&version=6.1.2                
nuke :add-package EdjCase.ICP.ClientGenerator --version 6.1.2                

Client Generator

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 used
  • no-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 false
  • url - (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 type canister
  • feature-nullable - (Bool) Optional. Sets whether to use the C# nullable feature when generating the client (like object?). Defaults to true
  • variants-use-properties - (Bool) Optional. If true, the generated variant classes will use properties instead of methods for data access. Defaults to false
  • 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
  • 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
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 id
      • cansiter-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 level output-directory. NOTE: this does not create a sub-folder based on the client name like the top level output-directory does
  • no-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 level no-folders
  • feature-nullable - (Bool) Optional. Sets whether to use the C# nullable feature when generating the client (like object?). Defaults to true. Overrides the top level feature-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 level keep-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 accessors
    • ClassWithProperties - 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# array
    • Dictionary - (Default if applicable) Uses a C# Dictionary<TKey, TValue>. Only works if the vec contains a record with 2 unamed fields (tuple). The first will be the key, the second will be the value
    • List - (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, but name is not supported

Opt Types Options
  • [clients.types.{CandidTypeId}.innerType]

    Uses the same options as the top level [clients.types.{CandidTypeId}] section, but name 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last updated
6.1.2 124 4/30/2024
6.1.1 102 4/17/2024
6.1.0 141 4/15/2024
6.0.0 177 3/21/2024
5.1.0 164 1/25/2024
5.0.0 217 1/12/2024
5.0.0-pre.2 183 12/13/2023
5.0.0-pre.1 95 12/11/2023
4.1.0 387 11/10/2023
4.0.1 401 11/1/2023
4.0.0 359 10/12/2023
4.0.0-pre.10 130 10/10/2023
4.0.0-pre.9 121 10/10/2023
4.0.0-pre.8 131 10/9/2023
4.0.0-pre.7 108 10/9/2023
4.0.0-pre.6 138 10/9/2023
4.0.0-pre.5 142 10/8/2023
4.0.0-pre.4 139 10/6/2023
4.0.0-pre.3 103 10/5/2023
4.0.0-pre.2 117 9/27/2023
4.0.0-pre.1 132 9/25/2023
3.2.2 451 9/22/2023
3.2.1 402 9/22/2023
3.2.0 378 8/2/2023
3.1.5 458 9/27/2023
3.1.4 322 7/20/2023
3.1.3 257 6/12/2023
3.1.2 355 5/11/2023
3.1.1 370 5/9/2023
3.1.0 276 5/9/2023
3.0.1 223 5/2/2023
3.0.0 268 5/1/2023
3.0.0-beta.1 138 4/17/2023
2.3.9 214 5/1/2023
2.3.8 219 4/28/2023
2.3.7 220 4/28/2023
2.3.6 186 4/28/2023
2.3.5 209 4/27/2023
2.3.4 204 4/27/2023
2.3.3 217 4/26/2023
2.3.2 240 4/26/2023
2.3.1 259 4/26/2023
2.3.0 265 4/25/2023
2.2.10 206 4/24/2023
2.2.9 231 4/24/2023
2.2.8 223 4/24/2023
2.2.7 239 4/17/2023
2.2.6 271 4/12/2023
2.2.5 270 4/12/2023
2.2.4 264 4/11/2023
2.2.3 286 4/11/2023
2.2.2 287 4/7/2023
2.2.1 296 4/7/2023
2.2.0 302 4/6/2023
2.1.1 289 3/30/2023
2.1.0 317 3/23/2023
2.0.8 362 3/20/2023
2.0.7 314 3/12/2023
2.0.2 336 3/10/2023
2.0.1 323 3/10/2023
2.0.0 302 3/8/2023
2.0.0-beta.26 140 3/8/2023
2.0.0-beta.25 132 3/8/2023
2.0.0-beta.24 121 3/7/2023
2.0.0-beta.23 123 3/6/2023
2.0.0-beta.22 127 3/1/2023
2.0.0-beta.21 132 2/28/2023
2.0.0-beta.20 129 2/20/2023
2.0.0-beta.19 131 2/14/2023
2.0.0-beta.18 130 2/14/2023
2.0.0-beta.17 124 2/14/2023
2.0.0-beta.16 129 2/11/2023
2.0.0-beta.15 124 2/10/2023
2.0.0-beta.14 124 2/6/2023
2.0.0-beta.13 129 2/3/2023
2.0.0-beta.12 139 2/2/2023
2.0.0-beta.11 135 1/30/2023
2.0.0-beta.10 132 1/23/2023
2.0.0-beta.9 128 1/19/2023
2.0.0-beta.7 124 1/12/2023
2.0.0-beta.6 122 12/31/2022
2.0.0-beta.5 115 12/30/2022
2.0.0-beta.4 118 12/21/2022
2.0.0-beta.3 130 12/19/2022
2.0.0-beta.2 116 12/10/2022
2.0.0-beta.1 127 12/2/2022
1.2.1 419 11/29/2022
1.2.0 382 11/28/2022
1.1.0 372 11/28/2022
1.0.3 403 11/25/2022
1.0.2 522 6/8/2022
1.0.1 504 6/7/2022
0.0.1-beta.20 157 6/1/2022
0.0.1-beta.19 162 5/20/2022
0.0.1-beta.14 160 5/19/2022