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

Ядро 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(".dcm", () => new DicomViewer()) — просмотрщик для расширения файла,
• builder.RegisterService<TContract>(() => …) — типизированный сервис, который могут искать другие части конвейера.

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

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

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

• Плагин, переопределяющий встроенный просмотрщик (он заявляет расширение, которое также обрабатывает встроенный просмотрщик): при наличии лицензии на возможность просмотрщик плагина выигрывает; без неё Doconut возвращается к встроенному просмотрщику. Пользователи всё равно видят документ; просто они не получают поведения плагина.
• Формат, поддерживаемый только плагином (.dcm и .ima — у DICOM нет встроенного просмотрщика): без возможности открытие не удаётся:

LicenseException: This document type requires the 'Dicom' plugin license.

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

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

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

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

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

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

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

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

Выводы

• Плагины регистрируются явно в DoconutHost.Initialize, и их возможности проверяются там; отсутствие прав останавливает сайт с пустым 500, причина которого записана в журнале событий Windows.
• Плагины в стиле переопределения деградируют плавно; форматы, поддерживаемые только плагинами, завершаются ошибкой с LicenseException.
• Активная временная лицензия разблокирует всё; продакшн разблокирует то, что вы купили. Проверьте с IDoconutLicenseService перед выпуском.