EdjCase.ICP.Agent 2.0.0-beta.8

ICP.NET

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

• Agent

  • Library to communicate to and from the Internet Computer
  • Nuget: EdjCase.ICP.Agent

• Candid

  • Library of Candid Encoding, Models and Helpers
  • Nuget: EdjCase.ICP.Candid

• Client Generator

  • Library of generating C# client code from *.did files
  • Nuget: EdjCase.ICP.ClientGenerator

• 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 identity
var identity = new AnonymousIdentity();

// Create http agent
IAgent agent = new HttpAgent(identity);

// 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 identity
var identity = new AnonymousIdentity();

// Create http agent
IAgent agent = new HttpAgent(identity);

// 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 identity
var identity = new AnonymousIdentity();

// Create http agent
IAgent agent = new HttpAgent(identity);

// 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

Links

• IC Http Interface Spec
• Candid Spec
• Candid Decoder
• Candid UI Tester