Налаштування ліцензії

Без ліцензії Doconut все ще рендерить документи — кожна сторінка лише містить водяний знак оцінки. Ця сторінка охоплює чотири способи надання ліцензії та точний порядок пріоритету, коли встановлено більше одного.

Ліцензія завантажується один раз, під час AddDoconut(). Це зміна порівняно з попередньою бібліотекою .NET Standard, де ліцензію передавали екземпляру Viewer або встановлювали через статичні виклики Viewer.DoconutLicense(...) / Viewer.SetLicensePlugin(...). Ці методи не є механізмом запуску у цьому випуску — дивіться посібник з міграції.

Чотири способи надання ліцензії

Існує чотири: три явних джерела в DoconutOptions — потік, сирий вміст або шлях до файлу — плюс автоматичне виявлення, коли жодне з них не встановлено. Коли встановлено більше одного, порядок пріоритету є точним:

LicenseStream переважає LicenseContent переважає LicensePath переважає auto-search.

За шляхом

LicensePath передається у File.Exists точно так, як вказано. Відносний шлях розв’язується відносно поточної робочої директорії процесу — не вашої папки проєкту і не папки, в якій знаходиться Program.cs. Якщо шлях не розв’язується, Doconut не генерує виключення і не переходить до автоматичного пошуку — просто не завантажує ліцензію, і переглядач додає водяний знак. Автоматичний пошук запускається лише коли жодне з LicensePath, LicenseContent або LicenseStream не встановлено. Файли ліцензій для кожного плагіна в тій же папці (Doconut.Viewer.<Capability>.lic) читаються разом з ним, тому LicensePath і AddPlugin<...>() працюють разом, коли ліцензії плагінів розташовані поруч з базовою ліцензією.

Рекомендується використовувати абсолютний шлях (наприклад, сформований з IWebHostEnvironment.WebRootPath або AppContext.BaseDirectory), або повністю пропустити LicensePath і покластися на автоматичне виявлення нижче.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

За потоком

LicenseStream читається один раз під час запуску — корисно, коли ліцензія береться з секретного сховища, а не з файлу на диску.

// Пріоритет: LicenseStream > LicenseContent > LicensePath > auto-search.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

За вмістом

LicenseContent приймає сам текст ліцензії — з змінної середовища, бази даних або менеджера секретів:

// XML ліцензії з бази даних, змінної середовища або менеджера секретів —
// без файлу на диску. Перевершується лише LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Автоматичне виявлення

Не налаштовуйте жодне з трьох явних джерел, і Doconut сам шукає ліцензію сам, лише у цих двох папках:

// Не налаштовуйте нічого, і Doconut шукає ліцензію сам, лише у цих двох папках:
//   1. {CurrentDirectory}/wwwroot
//   2. {AppContext.BaseDirectory}/wwwroot   (wwwroot всередині папки вихідних файлів збірки)
// Він спочатку шукає Doconut.lic, потім Doconut.Viewer.lic, плюс будь-які
// файли Doconut.Viewer.<Capability>.lic поруч з ним.
builder.Services.AddDoconut();

Папки для пошуку, у порядку, та імена файлів, які шукаються в кожній:

1. {CurrentDirectory}/wwwroot
2. {AppContext.BaseDirectory}/wwwroot

Імена файлів (перевіряються в кожній папці вище, у порядку):
  Doconut.lic                          — базова ліцензія переглядача (перевіряється першою)
  Doconut.Viewer.lic                   — базова ліцензія переглядача
  Doconut.Viewer.<Capability>.lic      — ліцензія для конкретної можливості, поруч з базовою ліцензією

Нічого поза папкою wwwroot не читається: .lic у самій вихідній папці або в wwwroot/lib ігнорується.

Якщо ви раніше передавали List<string> шляхів до ліцензій у конструктор Viewer — по одному для кожної можливості — залиште ці супутні файли поруч з Doconut.Viewer.lic і дозвольте автоматичному виявленню їх підхопити. Опції списку шляхів у DoconutOptions немає.

Скопіюйте ліцензію у вашу вихідну папку

Коли процес не запускається з папки проєкту — опублікованого застосунку, IIS, контейнера, тест‑раннера — перша спроба не вдається, і друга, {AppContext.BaseDirectory}/wwwroot, має знайти файл. Тестовий застосунок SDK копіює ліцензії туди при кожному збірці за допомогою цього MSBuild‑цілі:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
    <StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
  </ItemGroup>
  <!-- Спочатку видалити, щоб перейменування або видалення .lic у wwwroot також вилучало його з вихідного каталогу. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

Призначення має бути $(OutDir)wwwroot: .lic, скопійований у корінь вихідного каталогу, ніколи не буде знайдений автоматичним пошуком. Приклади LicensePath на цій сторінці вказують на те саме місце.

Тримайте файли .lic поза системою контролю версій — розгорніть їх разом із застосунком або впровадьте ліцензію через LicenseContent чи LicenseStream зі сховища секретів.

Що трапляється без ліцензії

Відсутня ліцензія не викликає виключення. AddDoconut() успішно виконується, застосунок стартує, і переглядач працює — проте кожна сторінка містить водяний знак оцінки, і жодна додаткова можливість не надається.

Файл ліцензії, який знайдено, але відхилено, — це інша ситуація. Недійсний підпис, підробка, чорний список або збірка поза вікном версії ліцензії призводять до того, що OpenDocumentAsync викидає LicenseException з License.RejectionMessage. Календарно прострочена ліцензія без повідомлення про відхилення продовжує працювати у режимі з водяним знаком.

Плагіни потребують можливостей

Реєстрація плагіна без відповідного дозволу — інша ситуація: для відсутньої ліцензії, застарілого файлу TRIAL або платної ліцензії без цієї можливості, AddDoconut() викидає InvalidOperationException, тому застосунок не запускається. Наприклад, реєстрація плагіна Converter без ліцензії, що надає Converter:

InvalidOperationException: The Converter plugin is registered via AddPlugin but no active
license grants Converter. Remove the AddPlugin<...>() call or install a license (or
trial/demo) that includes Converter.

Повідомлення одразу підказує, як виправити проблему: або видаліть виклик options.AddPlugin<...>() для цього плагіна, або встановіть платну ліцензію, чи активну тимчасову/демо (NFR) ліцензію, що надає цю можливість. Тимчасові реєстрації дозволяються після закінчення терміну дії, щоб вже налаштований застосунок міг перейти в обмежений режим замість аварійного завершення під час перезапуску; після прострочення їх можливості все одно відкликаються.

Перевірте завантажену ліцензію

Використовуйте IDoconutLicenseService, той самий джерело істини, що й SDK, щоб надати автентифіковану діагностичну кінцеву точку або керувати прапорцями функцій. Не повертайте вміст ліцензії чи ключі.

app.MapGet("/api/doconut/license", (IDoconutLicenseService license) => Results.Ok(new
{
    viewer = license.IsViewerLicensed || license.IsTemporary,
    temporary = license.IsTemporary,
    search = license.IsCapabilityGranted(LicenseCapability.Search),
    annotation = license.IsCapabilityGranted(LicenseCapability.Annotation),
    converter = license.HasConverter,
    dicom = license.HasDicom
}));

Ліцензію читають під час реєстрації AddDoconut(). ResetLicense наразі є властивістю сумісності без активного шляху перезавантаження, тому заміна файлу ліцензії вимагає перезапуску застосунку.

Матриця усунення проблем

Наступні кроки

• Ліцензування — можливості, рівні ліцензій та перевірка того, що було завантажено під час виконання.
• Усунення проблем — водяні знаки, відхилені ліцензії та помилки можливостей.