EdjCase.ICP.ClientGenerator 2.0.0-beta.12

This is a prerelease version of EdjCase.ICP.ClientGenerator.
There is a newer version of this package available.
See the version list below for details.
dotnet tool install --global EdjCase.ICP.ClientGenerator --version 2.0.0-beta.12                
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 2.0.0-beta.12                
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=EdjCase.ICP.ClientGenerator&version=2.0.0-beta.12&prerelease                
nuke :add-package EdjCase.ICP.ClientGenerator --version 2.0.0-beta.12                

ICP.NET

Collection of Internet Computer Protocol (ICP) libraries for .NET/Blazor

  • Agent

  • Candid

  • Client Generator

  • Internet Identity (Experimental)

    • Library of Internet Identity integration. Allowing computers to sign FIDO2/WebAuthn flows to login to Internet Identity
    • EXPERIMENTAL: Windows only for now and there are security implications
    • Nuget: EdjCase.ICP.InternetIdentity
  • Samples

    • A few projects to demo the capabilities of the ICP libraries
      • Blazor
      • AspNetCore
      • CLI

Agent

Usage (Manual)

  • Dont define any types and use CandidValue and CandidType
  • Call functions using Candid objects
// Create http agent with anonymous identity
IAgent agent = new HttpAgent();

// Create Candid arg to send in request
ulong proposalId = 1234;
CandidArg arg = CandidArg.FromCandid(
	new CandidTypedValue( // Candid type with no conversion
		value: CandidPrimitive.Nat64(proposalId),
		type: new CandidPrimitiveType(PrimitiveType.Nat64)
	)
);

// Make request to IC
string method = "get_proposal_info";
Principal governanceCanisterId = Principal.FromText("rrkah-fqaaa-aaaaa-aaaaq-cai");
QueryResponse response = await agent.QueryAsync(governanceCanisterId, method, arg);

QueryReply reply = response.ThrowOrGetReply();
// Convert to custom class
OptionalValue<ProposalInfo> info = reply.Arg.Values[0].ToOptionalObject<ProposalInfo>()

Usage (Self Defined Types)

  • Declare types of api models
  • Call functions and use custom object converters
// Create http agent with anonymous identity
IAgent agent = new HttpAgent();

// Create Candid arg to send in request
ulong proposalId = 1234;
CandidArg arg = CandidArg.FromCandid(
    CandidTypedValue.FromObject(proposalId) // Conversion can be C# or custom types
);

// Make request to IC
string method = "get_proposal_info";
Principal governanceCanisterId = Principal.FromText("rrkah-fqaaa-aaaaa-aaaaq-cai");
QueryResponse response = await agent.QueryAsync(governanceCanisterId, method, arg);

QueryReply reply = response.ThrowOrGetReply();
// Convert to custom class
OptionalValue<ProposalInfo> info = reply.Arg.Values[0].ToOptionalObject<ProposalInfo>() // Conversion to custom or C# types

Usage (w/ Client Generator)

  • Run Client Generator on *.did file (see Client Generator below)
  • Use generated client and models to call function
// Create http agent with anonymous identity
IAgent agent = new HttpAgent();

// Create new instance of client generated by `Client Generator` (this is using Governance.did for the NNS)
var client = new GovernanceApiClient(agent, Principal.FromText("rrkah-fqaaa-aaaaa-aaaaq-cai"));

// Make request
OptionalValue<ProposalInfo> info = await client.GetProposalInfoAsync(62143);

Candid

Parse from bytes

CandidArg arg = CandidArg.FromBytes(rawCandidBytes);

Reading candid values directly

CandidArg arg = CandidArg.FromBytes(rawCandidBytes);
CandidValue firstArg = arg.Values[0];
string title = firstArg.AsRecord()["title"];

Converting candid to and from custom classes

// Deserialize
CandidArg arg = CandidArg.FromBytes(rawCandidBytes);
MyObj obj = arg.Values[0].ToObject<MyObj>();
// Serialze
MyObj obj = new MyObj
{
    Title = "Title 1",
    IsGoodTitle = false
};
CandidTypedValue value = CandidTypedValue.FromObject(obj);

Variant

[Variant(typeof(MyVariantTag))] // Required to flag as variant and define options with enum
public class MyVariant
{
    [VariantTagProperty] // Flag for tag/enum property, not required if name is `Tag`
    public MyVariantTag Tag { get; set; }
    [VariantValueProperty] // Flag for value property, not required if name is `Value`
    public object? Value { get; set; }
}

public enum MyVariantTag
{
    [CandidName("o1")] // Used to override name for candid
    Option1,
    [CandidName("o2")]
    [VariantType(typeof(string))] // Used to specify if the option has a value associated
    Option2
}

Record

public class MyRecord
{
    [CandidName("title")] // Used to override name for candid
    public string Title { get; set; }
    [CandidName("is_good_title")]
    public bool IsGoodTitle { get; set; }
}

Other

C# -> Candid
UnboundedUInt -> Nat
byte -> Nat8
ushort -> Nat16
uint -> Nat32
ulong -> Nat64
UnboundedInt -> Int
sbyte -> Int8
short -> Int16
int -> Int32
long -> Int64
string -> Text
float -> Float32
double -> Float64
bool -> Bool
Principal -> Principal
OptionalValue<T> -> Opt T
List<T> -> Vec T
CandidFunc -> Func

Parse from Text

string text = "record { field_1:nat64; field_2: vec nat8 }";
CandidRecordType type = CandidTextParser.Parse<CandidRecordType>(text);

Generate Text representation

var type = new CandidRecordType(new Dictionary<CandidTag, CandidType>
{
    {
        CandidTag.FromName("field_1"),
        new CandidPrimitiveType(PrimitiveType.Nat64)
    },
    {
        CandidTag.FromName("field_2"),
        new CandidVectorType(new CandidPrimitiveType(PrimitiveType.Nat8))
    }
});
string text = CandidTextGenerator.Generator(type, IndentType.Tab);

Client Generator

Usage (Code)

    // Location of the `*.did` file to parse from
    string candidFilePath = "location/to/service.did";

    // Directory to create *.cs source code.
    string outputDirectory = "location/to/output";

    // Base namespace to give all *.cs files
    string @namespace = "My.Namespace.IC"

    // Optional, will use file name or type name if unspecified
    string? clientName = "MyClient";
    ClientFileGenerator.WriteClientFiles(candidFilePath, outputDirectory, @namespace, clientName);

Usage (dotnet tool)

Install with dotnet tools

dotnet tool install -g EdjCase.ICP.ClientGenerator

Run tool

candid-client-generator -f "location/to/service.did" -o "location/to/output" -n "My.Namespace.IC" -c "MyClient"

Installing local tool for development

Build with the version of src/ClientGenerator/EdjCase.ICP.ClientGenerator.csproj set to some pre-release version (anything not available in NuGet repositories).

e.g.:

(cd src/ClientGenerator/ ; dotnet pack --configuration Debug -property:Version=99.99.99-pre)
dotnet tool install EdjCase.ICP.ClientGenerator --local --add-source ./src/ClientGenerator/nupkg --version 99.99.99-pre --ignore-failed-sources

Internet Identity

Experimental library

  • Only works for Windows right now

Usage

ulong anchor = 1; // Internet Identity anchor
string hostname = "nns.ic0.app"; // Hostname to login to
LoginResult result = await Authenticator
    .WithHttpAgent() // Use http agent to communicate to the Internet Identity canister
    .LoginAsync(anchor, hostname);
    
DelegationIdentity identity = result.GetIdentityOrThrow(); // Gets the generated identity or throws if login failed

var agent = new HttpAgent(identity); // Use in agent to make authenticated requests
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.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.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
7.0.0 90 18 days ago
7.0.0-rc.1 85 a month ago
7.0.0-pre.1 75 3 months ago
6.2.1 176 3 months ago
6.2.0 131 3 months ago
6.1.2 167 9 months ago
6.1.1 141 10 months ago
6.1.0 185 10 months ago
6.0.0 239 3/21/2024
5.1.0 249 1/25/2024
5.0.0 309 1/12/2024
5.0.0-pre.2 207 12/13/2023
5.0.0-pre.1 119 12/11/2023
4.1.0 485 11/10/2023
4.0.1 521 11/1/2023
4.0.0 462 10/12/2023
4.0.0-pre.10 160 10/10/2023
4.0.0-pre.9 145 10/10/2023
4.0.0-pre.8 155 10/9/2023
4.0.0-pre.7 139 10/9/2023
4.0.0-pre.6 178 10/9/2023
4.0.0-pre.5 174 10/8/2023
4.0.0-pre.4 165 10/6/2023
4.0.0-pre.3 134 10/5/2023
4.0.0-pre.2 143 9/27/2023
4.0.0-pre.1 157 9/25/2023
3.2.2 548 9/22/2023
3.2.1 524 9/22/2023
3.2.0 436 8/2/2023
3.1.5 553 9/27/2023
3.1.4 402 7/20/2023
3.1.3 323 6/12/2023
3.1.2 412 5/11/2023
3.1.1 393 5/9/2023
3.1.0 343 5/9/2023
3.0.1 258 5/2/2023
3.0.0 307 5/1/2023
3.0.0-beta.1 156 4/17/2023
2.3.9 233 5/1/2023
2.3.8 261 4/28/2023
2.3.7 261 4/28/2023
2.3.6 222 4/28/2023
2.3.5 247 4/27/2023
2.3.4 242 4/27/2023
2.3.3 245 4/26/2023
2.3.2 262 4/26/2023
2.3.1 285 4/26/2023
2.3.0 307 4/25/2023
2.2.10 249 4/24/2023
2.2.9 277 4/24/2023
2.2.8 263 4/24/2023
2.2.7 278 4/17/2023
2.2.6 314 4/12/2023
2.2.5 308 4/12/2023
2.2.4 300 4/11/2023
2.2.3 307 4/11/2023
2.2.2 327 4/7/2023
2.2.1 335 4/7/2023
2.2.0 325 4/6/2023
2.1.1 331 3/30/2023
2.1.0 359 3/23/2023
2.0.8 396 3/20/2023
2.0.7 334 3/12/2023
2.0.2 371 3/10/2023
2.0.1 358 3/10/2023
2.0.0 342 3/8/2023
2.0.0-beta.26 155 3/8/2023
2.0.0-beta.25 153 3/8/2023
2.0.0-beta.24 137 3/7/2023
2.0.0-beta.23 144 3/6/2023
2.0.0-beta.22 141 3/1/2023
2.0.0-beta.21 149 2/28/2023
2.0.0-beta.20 149 2/20/2023
2.0.0-beta.19 150 2/14/2023
2.0.0-beta.18 146 2/14/2023
2.0.0-beta.17 141 2/14/2023
2.0.0-beta.16 145 2/11/2023
2.0.0-beta.15 152 2/10/2023
2.0.0-beta.14 140 2/6/2023
2.0.0-beta.13 147 2/3/2023
2.0.0-beta.12 155 2/2/2023
2.0.0-beta.11 151 1/30/2023
2.0.0-beta.10 148 1/23/2023
2.0.0-beta.9 144 1/19/2023
2.0.0-beta.7 138 1/12/2023
2.0.0-beta.6 143 12/31/2022
2.0.0-beta.5 138 12/30/2022
2.0.0-beta.4 134 12/21/2022
2.0.0-beta.3 146 12/19/2022
2.0.0-beta.2 132 12/10/2022
2.0.0-beta.1 144 12/2/2022
1.2.1 451 11/29/2022
1.2.0 400 11/28/2022
1.1.0 412 11/28/2022
1.0.3 434 11/25/2022
1.0.2 555 6/8/2022
1.0.1 534 6/7/2022
0.0.1-beta.20 172 6/1/2022
0.0.1-beta.19 177 5/20/2022
0.0.1-beta.14 177 5/19/2022