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

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

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

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

LicenseStream переважає LicenseContent, який переважає LicensePath, який переважає автоматичний пошук.

За шляхом

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

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

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

За потоком

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

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

За вмістом

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

// License XML from a database, environment variable, or secret manager —
// no file on disk. Beaten only by LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

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

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

// Configure nothing, and Doconut searches for the license itself:
//   1. {CurrentDirectory}/wwwroot
//   2. {CurrentDirectory}/wwwroot/lib
//   3. AppContext.BaseDirectory  (the build output folder)
// It looks for Doconut.Viewer.lic plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
builder.Services.AddDoconut();

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

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

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

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

LicensePath і автоматичний пошук у AppContext.BaseDirectory обидва потребують, щоб файл .lic існував поруч зі зібраним застосунком — а не лише у вашій вихідній папці wwwroot. Тестовий застосунок SDK копіює його при кожному збірці за допомогою цього MSBuild‑target:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
  </ItemGroup>
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)" SkipUnchangedFiles="true" />
</Target>

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

Матриця усунення неполадок

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

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