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

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

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

Існує чотири: три явних джерела на 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 > 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, а також будь‑які per-plugin
// файли 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-plugin license, alongside the base license

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

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

Коли процес не запускається з папки проєкту — опублікованого застосунку, 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 — водяні знаки, відхилені ліцензії та помилки можливостей.