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

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

Ядро 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>(() => …) — типизированный сервис, который могут искать другие части конвейера.

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

Возможности (capabilities) — это единицы лицензии. 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() генерируют пакеты скриптов/стилей для функций, ограниченных лицензией (поиск, аннотация, …) только когда лицензия их включает, поэтому UI виджета остаётся согласованным с тем, что действительно делает сервер.

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

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

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

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

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

ПлагинПакетВозможностьВклад
КонвертерDoconut.NET8.ConverterConverterВозможность конвертации документов
DICOMDoconut.NET8.DicomDicomПросмотр медицинских изображений (.dcm и .ima — форматы только плагина)
ПодписываниеDoconut.NET8.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 перед выпуском.

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