DoconutOptions

Настройка сервисов Doconut

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

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

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

Properties

ТипСвойствоПо умолчаниюОписание
boolShowDoconutInfofalseКогда true, запрос middleware без токена возвращает баннер версии (Doconut <version> is running on <host>) вместо 404. Полезно для быстрой проверки; оставьте false в продакшн.
boolUnsafeModefalseКогда true, пропускает проверку безопасности ASP.NET‑session при запросах страниц. Оставьте false в продакшн на единственном узле (см. Core Concepts → Sessions & Security). Ранее писалось UnSafeMode.
stringMiddlewarePath"/doconut"Координационное значение для конечной точки page-image. Оно проверяется, но не монтирует ветку конвейера; держите его согласованным с реальным сопоставлением UseDoconut() и клиентским BasePath.
stringResourcesPath"/doconut-res"Префикс URL‑пути для встроенных ресурсов JS/CSS/image/font.
stringLicensePath""Путь к файлу лицензии. Пустой → следующий источник лицензии, затем автообнаружение; ничего не найдено → состояние оценки с водяным знаком без возможностей.
stringLicenseContent""Необработанное XML‑содержимое лицензии (база данных, переменная окружения, менеджер секретов). Имеет приоритет над LicensePath.
Stream?LicenseStreamnullЛицензия как поток, читается один раз при запуске. Имеет приоритет над обоими другими источниками.
boolResetLicensefalseЗарезервированный флаг совместимости. Текущая реализация его не использует; перезапустите приложение после замены лицензии.
DoconutPluginRegistryPluginRegistry—Регистр только для чтения, собирающий вклады плагинов; используется фабрикой просмотрщика. Заполняется через AddPlugin<T>().

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

Methods

AddPlugin<TPlugin>()

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

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

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

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

RegisterViewer(extension, factory, defaultConfig?)

text
DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — ведущая точка необязательна
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

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

Бросает ArgumentException (Extension must be a non-empty file extension.) при пустом расширении и ArgumentNullException при null‑фабрике.

Startup validation

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

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Common configurations

csharp
// Продакшн: явная лицензия, всё заблокировано (все настройки безопасности по умолчанию)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Пользовательские пути (например, чтобы избежать конфликта маршрута)
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 этот префикс без начального / ('docs-engine'). Распространённая альтернатива сохраняет историческую форму запроса DocImage.axd на ветке MapWhen с BasePath: '/'.

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