DoconutOptions

DoconutOptions (namespace Doconut) — единственный объект конфигурации для всего SDK. Вы настраиваете его один раз внутри AddDoconut(), и он регистрируется как singleton.

Это изменение как в расположении, так и в форме. В предыдущей библиотеке .NET Standard экземпляр DoconutOptions создавался во время конвейера и передавался в UseDoconut(new DoconutOptions { … }). Здесь middleware не принимает никаких параметров — всё задаётся во время регистрации сервисов.

builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Свойства

Приоритет лицензий (применяется при регистрации сервисов): LicenseStream → LicenseContent → LicensePath → автоматическое обнаружение (см. Начало работы → Настройка лицензии).

Методы

AddPlugin<TPlugin>()

DoconutOptions AddPlugin<TPlugin>() where TPlugin : IDoconutPlugin, new()

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

Регистрирует плагин первой стороны (Converter, DICOM). Fluent‑метод — возвращает тот же экземпляр опций. AddDoconut() бросает InvalidOperationException, если отсутствует лицензия, найден устаревший файл TRIAL или платная лицензия не предоставляет возможности плагина. Временные/демо‑регистрации сохраняются после истечения срока и подпадают под runtime‑gate (см. Основные концепции → Система плагинов).

Виджет Converter включается через AddConverterWidget() и доступен через свойство только для чтения ConverterWidget; его параметры задокументированы на странице плагина Converter (Плагины → Плагин Converter).

RegisterViewer(extension, factory, defaultConfig?)

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

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

Бросает ArgumentException (Extension must be a non-empty file extension.) при пустом расширении и ArgumentNullException при null‑фабрике.
Переведённое сообщение: Extension must be a non-empty file extension. → Расширение должно быть непустым файловым расширением.

Проверка при запуске

AddDoconut() проверяет опции fail-fast, поэтому ошибка конфигурации проявляется в виде чёткого исключения при старте, а не в виде запутанных 404‑ов во время запросов:

DoconutOptions.MiddlewarePath должен быть непустым путём, начинающимся с '/'.
DoconutOptions.ResourcesPath должен быть непустым путём, начинающимся с '/'.
DoconutOptions.MiddlewarePath и ResourcesPath должны быть разными путями.

Распространённые конфигурации

// Production: explicit license, everything locked down (all security defaults)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Custom paths (e.g. to avoid a route conflict)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

Когда вы меняете ResourcesPath, синхронизируйте клиентский ResPath (см. ViewerConfig). Это одна из двух клиентских настроек, которые могут привести к сбою без сообщения об ошибке.

MiddlewarePath не является автоматическим маршрутизатором ASP.NET Core. Если Doconut должен отвечать только под пользовательским префиксом, смонтируйте UseDoconut() на этой ветке (например, app.Map("/docs-engine", branch => branch.UseDoconut())) и задайте клиенту BasePath тот же URL. В демонстрационном приложении вместо этого сохраняется историческая форма запроса DocImage.axd на ветке MapWhen с BasePath: '/'.