Skip to content

Getting Started

Install the IonPath compiler, create your first schema, and generate type-safe code.

Prerequisites

Install the CLI

Install ionc as a .NET global tool:

dotnet tool install -g ionc

Verify the installation:

$ ionc --version
ionc 1.3.2

Initialize a Project

Create a new directory and run ionc init to scaffold the project:

$ mkdir my-contracts && cd my-contracts
$ ionc init

This creates an ion.config.json file — the project manifest:

// ion.config.json
{
  "name": "MyContracts",
  "features": ["std"],
  "generators": {
    "dotnet": {
      "features": ["models", "client", "server"],
      "outputs": "./"
    },
    "browser": {
      "outputFile": "./client.generated.ts"
    }
  }
}

See Project Configuration for all options.

Write Your First Schema

Create a file called math.ion:

service MathInteraction(leftOperand: i4) {
    Add(rightOperand: i4): i4;
    Mul(rightOperand: i4): i4;
    PowArray(rightOperand: i4[]): i4[];
    ToPositive(rightOperand: i4?): i4?;
}

This defines a service with a base argument (leftOperand) that is shared across all methods, plus four RPC methods with various type modifiers.

Compile

Run the compiler:

$ ionc compile
✓ Compiled 1 module
✓ Generated C# (models, client, server)
✓ Generated TypeScript (browser)
✓ ion.lock.json updated

The compiler generates:

├── models/ — C# type definitions
├── client/ — C# client implementations
├── server/ — C# server executors
├── math.formatters.cs — CBOR serializers
├── moduleInit.cs — type aliases & registration
├── client.generated.ts — TypeScript client
└── ion.lock.json — schema lock

Useful Flags

Flag Description
--check Validate only — no code generation
--verbose Show detailed timing per compilation stage
--only dotnet Generate only for a specific target platform
--json Output diagnostics as JSON (for CI/CD)

See CLI Reference for all flags.

VS Code Extension

Install the IonPath Toolkit extension for:

  • Syntax highlighting for .ion files
  • JSON schema validation for ion.config.json
  • TextMate grammar support

Search for ionpath-toolkit in the VS Code marketplace or install from the extensions/ionpath-toolkit directory.

What's Next

Syntax Overview

Learn the full IonPath language syntax.

Primitive Types

All 27+ built-in types with mappings.

Project Configuration

ion.config.json schema reference.

Schema Lock

Understand wire-format stability.