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

Де Doconut шукає ваш файл ліцензії

Без ліцензії 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 і покладіться на автоматичне виявлення нижче.

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

За потоком

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

csharp
// Пріоритет: LicenseStream > LicenseContent > LicensePath > авто‑пошук.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

За вмістом

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

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

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

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

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

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

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

Filenames, in order (each one looked for in folder 1, then folder 2):
  Doconut.lic                          — legacy all-in-one license; if found, nothing else is read
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-capability licenses, read only when Doconut.Viewer.lic was found

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

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

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

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

xml
<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:

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

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

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

СимптомЙмовірна причинаПеревірка
Переглядач працює, але кожна сторінка має водяний знакЛіцензія не була завантажена, або Термінова ліцензія простроченаВирішіть IDoconutLicenseService; перевірте каталог виводу та робочий каталог процесу
AddDoconut() викидає для плагінаЛіцензія не надає цю можливість плагінуПеревірте IsCapabilityGranted(...) і видаліть реєстрації, які ви не придбали
Налаштований відносний шлях працює локально, але не в IIS/контейнеріРобочий каталог процесу змінивсяВикористайте AppContext.BaseDirectory або абсолютний шлях
Замінений файл .lic не має ефектуСервіс ліцензії-одиночка вже був створенийПерезапустіть застосунок
OpenDocumentAsync викидає LicenseExceptionПідпис, домен, часове вікно, чорний список або ворота виконання плагіна відхилили ліцензіюПрочитайте повідомлення про виключення/відхилення, не розкриваючи його недовіреним клієнтам
Перелік ліцензій за можливостями працював раніше, а тепер ніСтарий код передавав явні шляхи ліцензії конструктору ViewerПеремістіть супутні файли .lic поруч з Doconut.Viewer.lic і дозвольте автоматичному виявленню їх завантажити

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

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

Чи була ця сторінка корисною?