Система плагинов

Расширьте просмотрщик с помощью плагинов

Ядро Doconut остаётся лёгким; дополнительный функционал поставляется в виде плагинов — отдельных пакетов NuGet, которые предоставляют просмотрщики или сервисы и активируются вашей лицензией. На этой странице объясняется модель регистрации, как работает ограничение лицензией во время выполнения и как подключить собственный просмотрщик.

Регистрация плагина

Каждый пакет плагина предоставляет один класс плагина. Вы регистрируете его один раз при запуске:

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddPlugin<TPlugin>() создает экземпляр плагина и вызывает его Register обратный вызов в реестре плагинов, хранящемся в DoconutOptions. Всё, что предоставляет плагин, помечается требуемой возможностью плагина. AddDoconut() сразу проверяет зарегистрированные плагины: отсутствие лицензии, устаревший файл TRIAL или платная лицензия без этой возможности приводят к сбою запуска с InvalidOperationException. Регистрация Temporary/Demo сохраняется после истечения срока, но её возможности во время выполнения отзываются после даты истечения.

Контракт

Плагин реализует преднамеренно небольшой интерфейс:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // например "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // лицензионный шлюз
    void Register(IDoconutPluginBuilder builder); // вносить вклад в просмотрщики/службы
}

Внутри Register, построитель принимает два типа вкладов:

  • builder.RegisterViewer(extension, factory) — просмотрщик для расширения файла; фабрика возвращает IFormatViewer (плагин DICOM регистрирует .dcm и .ima таким образом),
  • builder.RegisterService<TContract>(() => …) — типизированный сервис, который могут искать другие части конвейера.

Возможности и ограничения

Возможности — это единицы лицензии. Converter, Dicom и Signer поставляются как плагины по запросу; Search и Annotation являются встроенными функциями, ограниченными тем же способом. Базовый просмотрщик не является возможностью — он является предварительным условием, представляемым как IsViewerLicensed в сервисе лицензий.

Проверка при запуске обычно не позволяет плагину без лицензии попасть в конвейер запросов. Фабрика просмотрщика также применяет два защитных правила во время выполнения, которые важны, если права меняются после запуска:

  • Плагин переопределяет встроенный просмотрщик (плагин заявляет расширение, которое также обрабатывается встроенным реестром): при наличии лицензии на возможность плагин‑просмотрщик выигрывает; без неё Doconut тихо переключается на встроенный просмотрщик. Пользователи всё равно видят свой документ — просто они не получают функцию плагина.
  • Формат только для плагина (.dcm и .ima — у DICOM нет встроенного просмотрщика): без возможности вызов open завершается с ошибкой:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Активная временная лицензия предоставляет все возможности (с чистым, без водяных знаков базовым просмотром). Это классический источник сюрпризов при вводе в эксплуатацию: регистрация тех же плагинов с приобретённой лицензией, в которой отсутствует одна из их возможностей, приводит к сбою AddDoconut() при запуске. Сравните IsCapabilityGranted(...) с вашим планом перед развертыванием. С другой стороны: при полном отсутствии лицензии ничего не предоставляется — отсутствие лицензии не является временной лицензией.

То же ограничение проявляется на клиенте: Viewer.ReferenceScripts() и ReferenceCss() генерируют пакеты скриптов/стилей для функций, ограниченных лицензией (поиск, аннотация, …) только когда лицензия их активирует, поэтому пользовательский интерфейс виджета остаётся согласованным с тем, что действительно делает сервер.

Карта функций и плагинов

В пользовательском интерфейсе продукта слово «плагин» используется как широкая метка функции, но регистрация на сервере отличается:

ФункцияКак включеноВозможностьВносит вклад
АннотацияВстроено в просмотрщик; включать ресурсы аннотацииAnnotationСоздание в браузере, сохранение сессии и экспорт с встраиванием
ПоискВстроено в просмотрщики форматов с поддержкой поиска; включать ресурсы поиска и включать извлечение при необходимостиSearchНативный текстовый индекс, подсветка и навигация по результатам
КонвертерУстановить Doconut.NET6.Converter и зарегистрировать ConverterPluginConverterСервис конвертации на C# и опциональный веб‑виджет
DICOMУстановить Doconut.NET6.Dicom и зарегистрировать DicomPluginDicomПросмотр медицинских изображений для .dcm и .ima
ПодписантУстановить Doconut.NET6.Signer и зарегистрировать SignerPluginSignerВидимые подписи и цифровые печати для PDF и Word: сервис подписи на C# и опциональный веб‑виджет

Аннотация и обычный Поиск не используют AddPlugin<TPlugin>(); их пакеты генерируются только когда лицензия предоставляет соответствующую возможность. Конвертер, DICOM и Подписант являются реализациями IDoconutPlugin по запросу.

Выпущенные пакеты плагинов

ПлагинПакетВозможностьВносит вклад
КонвертерDoconut.NET6.ConverterConverterВозможность конвертации документов
DICOMDoconut.NET6.DicomDicomПросмотр медицинских изображений (.dcm и .ima — форматы только для плагина)
ПодписантDoconut.NET6.SignerSignerПодпись PDF и Word

У каждого есть отдельная страница в разделе Plugins с его конфигурацией и использованием.

Пользовательские просмотрщики — ваш собственный обработчик формата

Вы можете подключить просмотрщик к конвейеру без написания пакета плагина, напрямую из Program.cs:

csharp
builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // реализует IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // необязательная конфигурация по умолчанию
});

// Обработчик формата, который создает фабрика. Замените эти члены своей собственной визуализацией.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
    public ViewerType ViewerType => ViewerType.None;
    public int TotalPages => 0;
    public int DefaultWidth => 0;
    public int DefaultHeight => 0;
    public bool PreferOcr => false;

    public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
        => Task.CompletedTask;

    public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
        => Task.FromResult(Array.Empty<byte>());

    public void Dispose() { }
}

Пользовательские просмотрщики имеют приоритет над всем — как над встроенными, так и над плагинами — и не ограничиваются лицензией (это ваш код). Фабрика переходит к ImageConfig, если вы не предоставляете конфигурацию по умолчанию.

Выводы

  • Плагины регистрируются явно, и их LicenseCapability проверяется во время AddDoconut() — отсутствие или недостаточное не временное право приводит к быстрому сбою.
  • Плагины в стиле переопределения деградируют плавно; форматы только для плагина завершаются с ошибкой LicenseException.
  • Активная временная лицензия разблокирует всё; продакшн разблокирует то, что вы купили. Проверьте с помощью IDoconutLicenseService перед выпуском.

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