Система плагинов
Расширьте просмотрщик с помощью плагинов
Ядро Doconut остаётся лёгким; дополнительный функционал поставляется в виде плагинов — отдельных пакетов NuGet, которые предоставляют просмотрщики или сервисы и включаются вашей лицензией. На этой странице объясняется модель регистрации, как работает ограничение лицензии во время выполнения и как подключить свой собственный просмотрщик.
Эта модель нова в данном выпуске. В предыдущей библиотеке .NET Standard не было реестра плагинов: конверсия была встроена в сам просмотрщик, а лицензии плагинов устанавливали через статические вызовы Viewer.SetLicensePlugin(...). Ни то, ни другое не является механизмом регистрации здесь.
Регистрация плагина
Каждый пакет плагина предоставляет один класс плагина. Вы регистрируете его один раз, при запуске:
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 сохраняется после истечения срока, но её возможности во время выполнения отзываются после даты истечения.
Контракт
Плагин реализует преднамеренно небольшой интерфейс:
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 нет встроенного просмотрщика): без возможности вызов открытия завершается с ошибкой:
LicenseException: This document type requires the 'Dicom' plugin license.Активная временная лицензия предоставляет все возможности (с чистым, без водяных знаков базовым просмотром). Это классический источник неожиданностей при запуске: регистрация тех же плагинов с приобретённой лицензией, в которой отсутствует одна из их возможностей, приводит к сбою AddDoconut() во время старта. Сравните IsCapabilityGranted(...) с вашим планом перед развертыванием. С другой стороны: при полном отсутствии лицензии ничего не предоставляется — отсутствие лицензии не является временной лицензией.
То же ограничение проявляется на клиенте: Viewer.ReferenceScripts() и ReferenceCss() генерируют пакеты скриптов/стилей для функций, ограниченных лицензией (поиск, аннотация, …) только когда лицензия их включает, поэтому пользовательский интерфейс виджета остаётся согласованным с тем, что действительно делает сервер.
Карта функций и плагинов
В пользовательском интерфейсе продукта слово «плагин» используется как широкая метка функции, но регистрация на сервере отличается:
| Функция | Как включается | Возможность | Вклад |
|---|---|---|---|
| Annotation | Встроено в просмотрщик; включены ресурсы аннотации | Annotation | Создание в браузере, сохранение сеанса и экспорт с встраиванием |
| Search | Встроено в просмотрщики форматов с поддержкой поиска; включены ресурсы поиска и включено извлечение при необходимости | Search | Нативный текстовый индекс, подсветка и навигация по результатам |
| Converter | Установите Doconut.NETStandard.Converter и зарегистрируйте ConverterPlugin | Converter | Сервис конвертации на C# и опциональный веб‑виджет |
| DICOM | Установите Doconut.NETStandard.Dicom и зарегистрируйте DicomPlugin | Dicom | Просмотр медицинских изображений для .dcm и .ima |
| Signer | Установите Doconut.NETStandard.Signer и зарегистрируйте SignerPlugin | Signer | Видимые подписи и цифровые печати для PDF и Word: сервис подписи на C# и опциональный веб‑виджет |
Аннотация и обычный поиск не используют AddPlugin<TPlugin>(); их пакеты генерируются только когда лицензия предоставляет соответствующую возможность. Конвертер, DICOM и Signer являются опциональными реализациями IDoconutPlugin.
Выпущенные пакеты плагинов
| Плагин | Пакет | Возможность | Вклад |
|---|---|---|---|
| Converter | Doconut.NETStandard.Converter | Converter | Возможность конвертации документов |
| DICOM | Doconut.NETStandard.Dicom | Dicom | Просмотр медицинских изображений (.dcm и .ima — форматы только для плагина) |
| Signer | Doconut.NETStandard.Signer | Signer | Подпись PDF и Word |
У каждого есть отдельная страница в разделе Plugins с его конфигурацией и использованием.
Пользовательские просмотрщики — ваш собственный обработчик формата
Вы можете подключить просмотрщик к конвейеру без написания пакета плагина, напрямую из Program.cs:
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перед выпуском.
Была ли эта страница полезной?