DoconutExtensions – Doconut Документація

DoconutExtensions (namespace Doconut.Middleware) — це статичний клас з трьома викликами, які виконує кожний хост Doconut: одна реєстрація сервісу та два виклики middleware.

csharp

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

AddDoconut

text

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

Створює DoconutOptions, швидко перевіряє їх (див. DoconutOptions → Startup validation), та реєструє повний граф сервісів:

Сервіс	Тривалість	Роль
`DoconutOptions`	Singleton	Об’єкт конфігурації
Session cache service	Singleton	Token → кеш сесії (`IMemoryCache` також зареєстровано)
`IDoconutLicenseService`	Singleton	Ліцензія завантажується один раз під час запуску (пріоритет: `LicenseStream` → `LicenseContent` → `LicensePath` → авто‑пошук)
Page-image pipeline	Singleton	Виконує обробку зображень сторінок (водяний знак, обертання, масштаб, анотації)
Document security (access store)	Singleton	Надає дозволи для прив’язки токен‑до‑сесії
`Viewer`	Transient	Публічний фасад відкриття/закриття
`DocumentConverter`	Transient	Фасад конвертації — потребує плагін Converter
`DistributedDocumentPublisher`	—	Публікує артефакти документа у спільне сховище
Health check `"doconut"`	—	Повідомляє про стан ліцензії/закінчення терміну через health‑checks ASP.NET

У попередній бібліотеці .NET Standard немає аналогічного виклику. Вона створювала new Viewer(cache, accessor) для кожного запиту та передавала параметри у middleware; обидва замінені цим одним реєстром.

Дві поведінки, які варто знати:

Converter потребує свій плагін. Вирішення DocumentConverter без options.AddPlugin<ConverterPlugin>() викликає виключення:

text

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Права плагіна перевіряються під час запуску. Відсутня ліцензія, застарілий файл TRIAL або платна ліцензія без зареєстрованої можливості плагіна призводить до помилки під час AddDoconut(). Тимчасові/демо‑реєстрації залишаються активними після дати закінчення, тоді як під час виконання шлюзи відкликають прострочені можливості.

Перевірка стану інтегрується зі стандартним механізмом ASP.NET Core — налаштуйте її, якщо хочете отримати стан ліцензії на вашому health‑endpoint:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Додає Doconut page-image middleware. Він відповідає на кожен запит, що містить параметр запиту ?token= — сторінки, мініатюри, пошук, анотації, дії зі сторінками (повна таблиця запитів у Core Concepts → How the Viewer Works). Коли UnsafeMode є false, шар безпеки документа підключається автоматично перед ним.

Він не приймає аргументів. Передача екземпляра DoconutOptions тут була у попередній бібліотеці і більше не компілюється.

Зразок посилання маршрутизує запити віджету через гілку шляху, зберігаючи історичну форму запиту:

csharp

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

Обслуговує вбудовані JS, CSS, зображення та шрифти за адресою DoconutOptions.ResourcesPath (за замовчуванням /doconut-res). Це файли, для яких Viewer.ReferenceCss() / ReferenceScripts() генерують теги.

Завжди викликайте його перед UseDoconut(). Якщо область переглядача залишається порожньою і консоль браузера показує 404 для /doconut-res/..., цей виклик відсутній або розташований неправильно.

Це підтримувана заміна ручного підключення middleware обробки вбудованих ресурсів.

Serving from shared storage

Існує ще два реєстрації для розгортань, де вузол, що генерує документ, не обов’язково є вузлом, що обслуговує його сторінки. Обидва покриті повністю у розділі Розподілені розгортання; сигнатури такі:

text

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // черга фонового публікування за згодою
IServiceCollection AddDoconutDistributedWidgets(...)        // спільне сховище для завантажень віджетів

Частина читання — це окремий middleware з пакету Doconut.Clouds:

text

IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

UseDoconutWebFarm(...) та WebFarmOptions не існують у цьому випуску. Дивіться посібник з міграції для покрокового зіставлення налаштувань.

Ordering recap

csharp

app.UseRouting();
app.UseSession();          // вимагається, коли UnsafeMode = false
app.UseDoconutResources(); // Перший виклик Doconut
app.UseDoconut();          // Другий виклик Doconut (або через гілку MapWhen)