Система плагинов
Расширьте просмотрщик с помощью плагинов
Ядро Doconut остаётся лёгким; дополнительный функционал поставляется в виде плагинов — отдельных пакетов NuGet, которые добавляют просмотрщики или сервисы и включаются в соответствии с вашей лицензией. Эта страница объясняет модель регистрации, что происходит при запуске, когда лицензия не покрывает плагин, и как подключить собственный просмотрщик.
Регистрация плагина
Каждый пакет плагина предоставляет один класс плагина. Зарегистрируйте его один раз, в Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Зарегистрированный плагин, у которого отсутствует лицензия, бросает исключение здесь, в Application_Start, и
// сайт затем отвечает на каждый запрос пустым 500. Причина находится в журнале событий Windows.AddPlugin<TPlugin>() создаёт плагин и позволяет ему зарегистрировать свои вклады с помощью DoconutOptions. Всё, что вносит плагин, помечается требуемой возможностью плагина, а DoconutHost.Initialize проверяет каждый зарегистрированный плагин относительно лицензии перед тем, как сайт обработает первый запрос.
Отсутствующая лицензия плагина останавливает сайт
Когда ни одна активная лицензия не предоставляет возможности зарегистрированного плагина — отсутствие лицензии, устаревший файл TRIAL или платная лицензия без этой возможности — DoconutHost.Initialize генерирует InvalidOperationException из Application_Start:
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.В System.Web исключение в Application_Start не приводит к отображению страницы ошибки. Каждый запрос получает пустой 500, журнал IIS не содержит полезной информации, а сообщение появляется только в журнале событий Windows (журнал Приложений, источник ASP.NET). Если сайт перестаёт отвечать сразу после добавления строки AddPlugin, сначала проверьте файлы лицензий в wwwroot — см. Настройка лицензии.
Контракт
Плагин реализует преднамеренно небольшой интерфейс:
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.Активная временная лицензия предоставляет все возможности. Это классический сюрприз при запуске: те же строки AddPlugin, которые работали во время оценки, останавливают сайт, когда приобретённая лицензия не включает одну из этих возможностей. Сравните IsCapabilityGranted(...) с тем, что вы приобрели перед развертыванием. При полном отсутствии лицензии ничего не предоставляется — отсутствие лицензии не является временной лицензией.
То же ограничение распространяется на браузер: Viewer.ReferenceScripts() и ReferenceCss() отдают файлы для функций, ограниченных лицензией (Поиск, Аннотация) только когда лицензия их предоставляет, поэтому страница никогда не предлагает функцию, которую сервер откажет обслужить.
Карта функций и плагинов
| Функция | Как включается | Возможность | Вносит |
|---|---|---|---|
| Аннотация | Встроено в просмотрщик; включить ресурсы аннотации | Annotation | Авторинг в браузере, сохранение сессии, экспорт с встраиванием |
| Поиск | Встроено в просмотрщики, поддерживающие поиск; включить ресурсы поиска | Search | Нативный текстовый индекс, подсветка, навигация по результатам |
| Конвертер | Установить Doconut.NETFramework.Converter и зарегистрировать ConverterPlugin | Converter | Сервис конвертации на C# и необязательный веб‑виджет |
| DICOM | Установить Doconut.NETFramework.Dicom и зарегистрировать DicomPlugin | Dicom | Просмотр медицинских изображений для .dcm и .ima |
| Подписывающий | Установить Doconut.NETFramework.Signer и зарегистрировать SignerPlugin | Signer | Видимые подписи и цифровые печати для PDF и Word: сервис подписи на C# и необязательный веб‑виджет |
Аннотация и Поиск не используют AddPlugin<TPlugin>(). Конвертер, DICOM и Подписывающий каждый имеют страницу в разделе Плагины со своей конфигурацией и использованием. В этом пакете DICOM отображает страницы, кадры и анимацию, но не читает технические метаданные — см. Плагин DICOM.
Пользовательские просмотрщики — ваш собственный обработчик формата
Вы можете подключить просмотрщик к конвейеру без создания пакета плагина, напрямую в Application_Start:
Doconut.DoconutHost.Initialize(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.
Выводы
- Плагины регистрируются явно в
DoconutHost.Initialize, и их возможности проверяются там; отсутствие права останавливает сайт с пустым500, причина которого записана в журнале событий Windows. - Плагины, переопределяющие встроенные, деградируют плавно; форматы, поддерживаемые только плагинами, завершаются ошибкой с
LicenseException. - Активная временная лицензия открывает всё; в продакшене открываются только приобретённые возможности. Проверьте с помощью
IDoconutLicenseServiceперед выпуском.
Была ли эта страница полезной?