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>();
});

Властивості

Тип	Властивість	За замовчуванням	Опис
`bool`	`ShowDoconutInfo`	`false`	Коли `true`, запит до middleware без токену повертає банер версії замість 404. Корисно для швидкої перевірки; у продакшн залишайте `false`.
`bool`	`UnsafeMode`	`false`	Коли `true`, пропускає перевірку безпеки ASP.NET‑session під час запитів сторінок. У продакшн на одиночному вузлі залишайте `false` (див. Основні концепції → Сесії та безпека). Раніше називалося `UnSafeMode`.
`string`	`MiddlewarePath`	`"/doconut"`	Координаційне значення для кінцевої точки page‑image. Перевіряється, але не монтує гілку конвеєра; тримайте його синхронізованим з фактичним мапінгом `UseDoconut()` та клієнтським `BasePath`.
`string`	`ResourcesPath`	`"/doconut-res"`	Префікс URL‑шляху для вбудованих ресурсів JS/CSS/зображень/шрифтів.
`string`	`LicensePath`	`""`	Шлях до файлу ліцензії. Порожньо → наступне джерело ліцензії, потім автоматичне виявлення; якщо нічого не знайдено → стан оцінки з водяним знаком без можливостей.
`string`	`LicenseContent`	`""`	Необроблений XML‑вміст ліцензії (база даних, змінна оточення, менеджер секретів). Має пріоритет над `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Ліцензія у вигляді потоку, читається один раз під час запуску. Має пріоритет над обома іншими джерелами.
`bool`	`ResetLicense`	`false`	Зарезервований прапорець сумісності. Поточна реалізація його не використовує; перезапустіть застосунок після заміни ліцензії.
`DoconutPluginRegistry`	`PluginRegistry`	—	Реєстр лише для читання, що збирає внески плагінів; використовується фабрикою переглядачів. Заповнюється через `AddPlugin<T>()`.

Пріоритет ліцензій (застосовується під час реєстрації сервісу): LicenseStream → LicenseContent → LicensePath → автоматичне виявлення (див. Початок роботи → Налаштування ліцензії).

Методи

AddPlugin()

text

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

Використовуйте цей метод для випущених opt‑in пакетів Converter та DICOM. Анотація та звичайний Search — вбудовані ліцензовані функції і не використовують AddPlugin<TPlugin>().

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

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

RegisterViewer(extension, factory, defaultConfig?)

text

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‑фабрики.

Перевірка запуску

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.

Поширені конфігурації

csharp

// 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: '/'.