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

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

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`	Одинарний	Об’єкт конфігурації
`IViewerFactory`	Одинарний	Відповідає розширенням до переглядачів форматів
`IDocumentSessionManager`	Одинарний	Токен → кеш сесії (`IMemoryCache` також зареєстровано)
`IDoconutLicenseService`	Одинарний	Ліцензія завантажується один раз під час запуску (пріоритет: `LicenseStream` → `LicenseContent` → `LicensePath` → автоматичний пошук)
`PageImageService`	Одинарний	Конвеєр обробки зображень сторінок (водяний знак/повернення/масштаб/анотації)
Document security (access store)	Одинарний	Надання прав для прив’язки токен‑сесія
`Viewer`	Тимчасовий	Публічний інтерфейс відкриття/закриття
`DocumentConverter`	Тимчасовий	Інтерфейс конвертації — потребує плагін Converter
`DistributedDocumentPublisher`	—	Публікує артефакти документа у спільне сховище
Health check `"doconut"`	—	Повідомляє про стан ліцензії/закінчення терміну через перевірки здоров’я ASP.NET

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

Дві важливі поведінки:

Конвертер вимагає свій плагін. Спроба отримати 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 — підключіть її, якщо вам потрібен стан ліцензії на вашому ендпоінті здоров’я:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Додає проміжне програмне забезпечення Doconut для обробки зображень сторінок. Воно відповідає на кожен запит, що містить параметр ?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/..., цей виклик відсутній або розташований неправильно.

Це підтримувана заміна ручного підключення проміжного програмного забезпечення вбудованих ресурсів за допомогою app.UseMiddleware<EmbeddedResourceMiddleware>().

Обслуговування зі спільного сховища

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

text

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // opt-in background publish queue
IServiceCollection AddDoconutDistributedWidgets(...)        // shared backing store for widget uploads

Читальна сторона — це окреме проміжне програмне забезпечення з пакету Doconut.Clouds:

text

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

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

Підсумок порядку викликів

csharp

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1‑ий виклик Doconut
app.UseDoconut();          // 2‑ий виклик Doconut (або через гілку MapWhen)