jsonpythonwill / icp.net

A library for .NET/C#/Unity to natively communicate with the Internet Computer (ICP)

ICP.NET

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

• Agent - Library to communicate to and from the Internet Computer

• Candid - Library of Candid Encoding, Models and Helpers

• Client Generator - Client source code generator for ICP canisters

See each individual project README for more in depth guides

🎮 Unity Integration

• Download latest agent.unitypackage from: https://github.com/edjCase/ICP.NET/releases
• Import agent.unitypackage into your unity project
• If using WebGL, follow the additional WebGL instructions in the Agent Docs
• If generating a client (see below), place the generated files into the scripts folder: Assets/scripts/MyClient
• Start coding 💻

📡 Generating a client for a canister

You can specify all the models and api calls yourself, but this is a tool to automatically generate a client and models based on the cansiter or .did file

• Prerequisite: Have .Net 6 installed (https://dotnet.microsoft.com/en-us/download/dotnet)

• Navigate to directory of .Net project

  cd {path/to/project}
  

• Add Agent nuget package to project

  dotnet add package EdjCase.ICP.Agent
  

• Install ClientGenerator

  dotnet tool install -g EdjCase.ICP.ClientGenerator
  

  This will allow a client to be automatically be generated for a canister. See ClientGenerator README for more details and advanced config

• Initialize ClientGenerator config (first run only)

  candid-client-generator init
  

  This will create a TOML config file in the directory that can be changed for more advanced options

• Update created config file candid-client.toml

  If using a canister id:

  namespace = "ProjectGovernance" # Base namespace to use
  output-directory = "./Clients" # Output directory
  
  [[clients]]
  name = "Governance" # Label of client to use
  type = "canister" # Indicates to make client from a canister id
  canister-id = "rrkah-fqaaa-aaaaa-aaaaq-cai" # Canister id to make client for

  If using a service definition file (.did)

  namespace = "ProjectGovernance" # Base namespace to use
  output-directory = "./Clients" # Output directory
  
  [[clients]]
  name = "Governance" # Label of client to use
  type = "file" # Indicates to make client from a service definition file
  file-path = "Governance.did" # File to use

  For all configuration options see ClientGenerator README for more details

• Generate Client

  candid-client-generator gen
  

  Will output C# file to the output directory specified in the config

• Use client in code

  var agent = new HttpAgent();
  Principal canisterId = Principal.FromText("rrkah-fqaaa-aaaaa-aaaaq-cai");
  var client = new GovernanceApiClient(agent, canisterId);
  OptionalValue<Sample.Shared.Governance.Models.ProposalInfo> proposalInfo = await client.GetProposalInfo(110174);
  ...

• SHIP IT! 🚀

Breaking change migrations

3.x.x => 4.x.x

The big change here was around variant classes and their attributes. Before the option types were defined by the attribute on each enum member, but in 4.x.x it changed to using method return types and having not type information in attributes. Also the VariantAttribute now gets the enum type from the Tag property vs the attribute

Version 3

[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
}

Version 4

[Variant] // Required to flag as variant
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; }


	// This method is used to specify if the option has a type/value associated
	[VariantOption("o2")] // Specify the candid tag if different than 'As{CandidTag}' like 'Option2' here
	public string AsOption2()
	{
		return (string)this.Value!;
	}
}

public enum MyVariantTag
{
    [CandidName("o1")] // Used to override name for candid
    Option1,
    [CandidName("o2")]
    Option2
}

Candid Related Links

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