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

Where Doconut looks for your license file

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

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 и любые
// per-plugin 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-plugin licenses, read only when Doconut.Viewer.lic was found

Ничего за пределами папки wwwroot не читается: .lic в самой папке вывода или в wwwroot/lib игнорируется.

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

Когда процесс не запускается из папки проекта — опубликованное приложение, 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Подпись, домен, окно версии, черный список или проверка выполнения плагина отклонили лицензиюПрочитайте сообщение об исключении/отклонении, не раскрывая его недоверенным клиентам

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

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

Была ли эта страница полезной?