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

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

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

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

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

LicenseStream перевищує LicenseContent перевищує LicensePath перевищує авто‑пошук.

За шляхом

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 > автопошук.
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, а також будь‑які per-capability
// файли Doconut.Viewer.<Capability>.lic поруч із ним.
builder.Services.AddDoconut();

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

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

Filenames (checked in each folder above, in order):
  Doconut.lic                          — base viewer license (checked first)
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-capability license, alongside the base license

Ніщо поза папкою 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 наразі є властивістю сумісності без активного шляху перезавантаження, тому заміна файлу ліцензії вимагає перезапуску застосунку.

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

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

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