Skip to main content

How to start

This is written for a configuration developer: someone building their own business application on the Kandra platform. You do not need — and by default won't have — a checkout of the Kandra platform's own source. Your configuration is its own self-contained git repo, consuming Kandra.* purely as NuGet packages.

Prerequisites​

  • .NET SDK matching net10.0.
  • Network access to Kandra's public NuGet feed, https://nugets.kandra.tech/index.json. It is anonymous: no account, no token, no environment variable. Kandra.* is not on nuget.org, so every command below that downloads a Kandra package names this feed (see The NuGet feed).

1. Install the scaffolding tools​

Install the template first, then (optionally) the interactive wizard:

dotnet new install Kandra.ConfigTemplate --add-source https://nugets.kandra.tech/index.json
dotnet tool install --global Kandra.ConfigCreateTool --add-source https://nugets.kandra.tech/index.json

The wizard is a friendlier front end over the same template — it does no file manipulation of its own, it just prompts you and runs the dotnet new kandra-config command below for you. Installing the wizard does not install the template, which is why the template comes first. The template's migration tool (kandra-migrate) needs no separate install: the scaffold pins it in .config/dotnet-tools.json and restores it for you (step 2).

2. Scaffold your configuration​

dotnet new kandra-config -n Acme --IncludeSqlite

or, with the wizard installed:

kandra-new-config
  • -n <Name> — your configuration's name. Every project in the scaffold is prefixed with it (Acme.Domain, Acme.Forms, Acme.WebApi, ...).
  • --IncludeSqlite (default true), --IncludeSqlServer (default false), --IncludePostgres (default false) — pick one or more EF Core providers. Picking none prints a warning and skips the restore step instead of leaving you with a solution that won't compile.

dotnet new then asks whether to run the template's post-action, dotnet tool restore, which installs dotnet-ef and kandra-migrate as local tools in the new folder. Answer y, or pass --allow-scripts yes to skip the question (the wizard does). If you decline, run dotnet tool restore in the new folder yourself.

This produces an empty, buildable, 11-project solution — the same project shape as KandraWms (the platform team's own reference configuration), with every domain-specific piece stripped out, referencing the Kandra platform purely via NuGet PackageReference. There is no platform source anywhere in your new repo — see Overall architecture for exactly what that 11-project shape looks like.

3. Restore, build, run​

cd Acme
dotnet restore
dotnet build Acme.slnx
dotnet run --project src/Acme.WebApi

It starts empty — no Dictionaries, Documents, Reports, Registers, or Data Processors yet — but it's fully runnable as scaffolded: you'll see a working login and an empty nav menu.

The NuGet feed​

Kandra's packages are served from a public, anonymous feed: https://nugets.kandra.tech/index.json. The scaffolded repo already contains a complete nuget.config that wires it in, so dotnet restore just works. If you add the feed to an existing solution (or to another machine), copy this file next to your .slnx:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="Kandra" value="https://nugets.kandra.tech/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="Kandra">
      <package pattern="Kandra.*" />
      <package pattern="KandraWms.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Why the packageSourceMapping block matters. NuGet does not prefer sources in the order listed: without a mapping it takes the best version match from any source. Anyone could publish a package named Kandra.Domain with a higher version number on nuget.org, and your next restore would pick it up (a dependency confusion attack). With the mapping, Kandra.* and KandraWms.* restore only from the Kandra feed and everything else only from nuget.org; a same-named package on the wrong source is simply never considered. If you publish your own configuration's packages to a private feed, add that feed and its prefix as a third packageSource.

The --add-source flags in step 1 exist only because dotnet new install and dotnet tool install run before any nuget.config exists. Once you have the file above (or run them from a folder that has one), they are not needed.

Two practical notes:

  • Pin exact versions. Kandra is pre-1.0 and may change between versions. All Kandra.* packages ship together under one version and only work as a matched set: reference the same version of every one you use. The scaffold does this through a single version property in Directory.Build.props.
  • Licence. The packages are proprietary software with a free tier, not open source. The licence terms are the Kandra End-User License Agreement, included in every package (EULA.md, and EULA.uk.md in Ukrainian); third-party components are listed in THIRD-PARTY-NOTICES.md.

4. Add your first entity — use the shipped skills​

Your scaffolded repo ships its own .claude/skills/ (one skill per entity kind: create-dictionary, create-document, create-register, create-report, create-data-processor, create-constant, create-enum, plus create-handler, create-ui-behavior, post-to-accounting, add-account-subconto-field, add-interface-node, create-print-form, convert-dictionary-to-hierarchical) and its own CLAUDE.md, written specifically for someone building on this scaffold — not the same file as the platform team's own CLAUDE.md. If you're using Claude Code, prefer invoking these skills over hand-rolling an entity's shape from scratch — that's the explicit guidance the scaffold ships with, not just a suggestion from this site. The "Creating a..." guides in this section give you the conceptual background each skill assumes; the skill itself does the mechanical work in your repo.

Running tests​

dotnet test Acme.slnx

One smoke test ships by default, proving the checked-in migrations apply cleanly against SQLite in-memory — see Testing.

Database migrations​

See Database migrations — your scaffolded repo already ships the manifest kandra-migrate needs, so that's the tool to reach for; raw dotnet ef per provider is the fallback if the tool isn't installed in your setup yet.

Exploring the platform's own reference configuration (optional)​

Everything above is self-contained — you never need the Kandra platform's own source to build a configuration. The skills' worked examples intentionally reuse real entity names from a previously-built configuration (each skill says so up front) rather than a fabricated generic example, specifically so you're looking at verified working code even without that access. If you want to go further and read the platform team's own reference configuration source directly, that means access to their internal monorepo — separate from the packages feed above, and something most configuration developers won't need.

Where to go next​