Настройка лицензии

Без лицензии 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 > авто-поиск.
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>
  <!-- Delete first, so renaming or removing a .lic in wwwroot also takes it out of the output. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

Назначение должно быть $(OutDir)wwwroot: .lic, скопированный в корень вывода, никогда не будет найден авто-поиском. Примеры LicensePath на этой странице указывают на то же место.

Держите файлы .lic вне системы контроля версий — размещайте их рядом с приложением или внедряйте лицензию через LicenseContent или LicenseStream из вашего секретного хранилища.

Что происходит без лицензии

Отсутствие лицензии не приводит к исключению. AddDoconut() успешно выполняется, приложение запускается, и просмотрщик работает — но каждая страница содержит водяной знак оценки, и ни одна дополнительная возможность не предоставляется.

Файл лицензии, который найден, но отклонён, отличается. Неправильная подпись, вмешательство, занесение в чёрный список или сборка вне окна версии лицензии вызывают исключение LicenseException у OpenDocumentAsync с 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<...>() для этого плагина, либо установить платную лицензию или активную временную/Demo (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 в настоящее время является совместимым свойством без активного пути перезагрузки, поэтому замена файла лицензии требует перезапуска приложения.

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

Следующие шаги

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