Як почати

Ця сторінка написана для розробника конфігурації: того, хто створює власний бізнес- застосунок на платформі Kandra. Вам не потрібен — і за замовчуванням у вас його не буде — чекаут вихідного коду самої платформи Kandra. Ваша конфігурація — це власний, самодостатній git-репозиторій, який використовує Kandra.* виключно як NuGet-пакети.

Передумови

• .NET SDK, що відповідає net10.0.
• Мережевий доступ до публічного NuGet-фіда Kandra, https://nugets.kandra.tech/index.json. Він анонімний: жодного облікового запису, токена чи змінної середовища. Kandra.* немає на nuget.org, тому кожна команда нижче, що завантажує пакет Kandra, вказує цей фід (дивіться NuGet-фід).

1. Встановіть інструменти скафолдингу

Спочатку встановіть шаблон, потім (за бажанням) інтерактивний майстер:

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

Майстер — це дружніший інтерфейс над тим самим шаблоном: він не виконує жодних файлових операцій сам, лише запитує вас і запускає команду dotnet new kandra-config нижче за вас. Встановлення майстра не встановлює шаблон, тому шаблон іде першим. Інструмент міграцій шаблону (kandra-migrate) окремого встановлення не потребує: скафолд закріплює його в .config/dotnet-tools.json і відновлює за вас (крок 2).

2. Створіть вашу конфігурацію

dotnet new kandra-config -n Acme --IncludeSqlite

або, якщо встановлено майстер:

kandra-new-config

• -n <Name> — назва вашої конфігурації. Кожен проєкт у згенерованому рішенні матиме цей префікс (Acme.Domain, Acme.Forms, Acme.WebApi, ...).
• --IncludeSqlite (за замовчуванням true), --IncludeSqlServer (за замовчуванням false), --IncludePostgres (за замовчуванням false) — оберіть один або кілька провайдерів EF Core. Якщо не обрати жодного, буде виведено попередження, а крок відновлення пакетів пропущено — замість рішення, яке не компілюється.

Далі dotnet new запитає, чи виконати post-action шаблону, dotnet tool restore, який встановлює dotnet-ef і kandra-migrate як локальні інструменти в новій теці. Дайте відповідь y або передайте --allow-scripts yes, щоб пропустити запитання (майстер так і робить). Якщо відмовитеся, виконайте dotnet tool restore у новій теці самостійно.

Це створює порожнє, готове до збірки рішення з 11 проєктів — таку саму форму проєктів, що й KandraWms (власна еталонна конфігурація команди платформи), з видаленими всіма доменно-специфічними частинами, що посилається на платформу Kandra виключно через NuGet PackageReference. У вашому новому репозиторії немає жодного вихідного коду платформи — дивіться Загальна архітектура для детального опису цієї структури з 11 проєктів.

3. Відновлення, збірка, запуск

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

Спочатку все порожньо — немає жодних Довідників, Документів, Звітів, Регістрів чи Обробників даних — але застосунок повністю працездатний одразу після створення: ви побачите робочий екран входу та порожнє меню навігації.

NuGet-фід

Пакети Kandra надаються з публічного анонімного фіда: https://nugets.kandra.tech/index.json. Згенерований репозиторій уже містить повний nuget.config, що підключає його, тож dotnet restore працює одразу. Якщо ви додаєте фід до наявного рішення (або на іншу машину), скопіюйте цей файл поруч зі своїм .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>

Навіщо потрібен блок packageSourceMapping. NuGet не віддає перевагу джерелам за порядком у списку: без мапінгу він бере найкращий збіг за версією з будь-якого джерела. Будь-хто може опублікувати на nuget.org пакет Kandra.Domain з вищою версією, і ваше наступне відновлення підхопить його (атака dependency confusion). З мапінгом Kandra.* і KandraWms.* відновлюються лише з фіда Kandra, а все інше — лише з nuget.org; пакет з такою самою назвою на хибному джерелі просто ніколи не розглядається. Якщо ви публікуєте пакети власної конфігурації у приватний фід, додайте цей фід і його префікс як третє packageSource.

Прапорці --add-source у кроці 1 потрібні лише тому, що dotnet new install і dotnet tool install виконуються до появи будь-якого nuget.config. Коли файл вище вже є (або ви запускаєте їх із теки, де він лежить), вони не потрібні.

Дві практичні примітки:

• Закріплюйте точні версії. Kandra ще не досягла 1.0 і може змінюватися між версіями. Усі пакети Kandra.* випускаються разом під однією версією й працюють лише як узгоджений набір: посилайтеся на одну й ту саму версію кожного з тих, що використовуєте. Скафолд робить це через єдину властивість версії в Directory.Build.props.
• Ліцензія. Пакети — це пропрієтарне програмне забезпечення з безкоштовним рівнем, а не відкритий код. Умови ліцензії — Ліцензійна угода кінцевого користувача Kandra (EULA), що входить до кожного пакета (EULA.md, а українською — EULA.uk.md); сторонні компоненти перелічено в THIRD-PARTY-NOTICES.md.

4. Додайте вашу першу сутність — використовуйте вбудовані навички

Ваш згенерований репозиторій постачається з власною папкою .claude/skills/ (по одній навичці на вид сутності: create-dictionary, create-document, create-register, create-report, create-data-processor, create-constant, create-enum, а також create-handler, create-ui-behavior, post-to-accounting, add-account-subconto-field, add-interface-node, create-print-form, convert-dictionary-to-hierarchical) та власним файлом CLAUDE.md, написаним спеціально для роботи саме з цим згенерованим репозиторієм — це інший файл, ніж власний CLAUDE.md команди платформи. Якщо ви використовуєте Claude Code, надавайте перевагу викликам цих навичок, а не ручному відтворенню форми сутності з нуля — це явна рекомендація, з якою постачається шаблон, а не просто порада цього сайту. Посібники «Створення...» в цьому розділі дають концептуальний контекст, який передбачає кожна навичка; саму механічну роботу у вашому репозиторії виконує навичка.

Запуск тестів

dotnet test Acme.slnx

За замовчуванням постачається один smoke-тест, що підтверджує, що вже готові міграції застосовуються без помилок до SQLite в пам'яті — дивіться Тестування.

Міграції бази даних

Дивіться Міграції бази даних — ваш згенерований репозиторій вже містить маніфест, потрібний kandra-migrate, тож саме цей інструмент варто використовувати; прямий виклик dotnet ef для кожного провайдера — це резервний варіант, якщо інструмент ще не встановлено у вашому середовищі.

Дослідження власної еталонної конфігурації команди платформи (опціонально)

Усе вище — самодостатнє: вам ніколи не потрібен вихідний код самої платформи Kandra, щоб створити конфігурацію. Робочі приклади навичок навмисно повторно використовують реальні назви сутностей з попередньо створеної конфігурації (кожна навичка одразу про це попереджає), а не вигаданий загальний приклад — саме для того, щоб ви дивилися на перевірений робочий код навіть без такого доступу. Якщо ви хочете піти далі й прочитати вихідний код власної еталонної конфігурації команди платформи напряму, це означає доступ до їхнього внутрішнього монорепозиторію — окремий від фіда пакетів вище, і те, що більшості розробників конфігурацій не знадобиться.

Куди йти далі

• Загальна архітектура — як складаються частини перед тим, як почати додавати сутності.
• Створення довідника — зазвичай перше конкретне, що ви створите.