DoconutExtensions
Реєстрація сервісів та проміжного ПЗ
DoconutExtensions (namespace Doconut.Middleware) — це статичний клас з трьома викликами, які робить кожний хост Doconut: одна реєстрація сервісу та дві реєстрації проміжного ПЗ.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // викличте UseSession() перед UseDoconut()
app.UseDoconutResources(); // повинно бути зареєстровано перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() відповідає на кожен запит, що до нього надходить, тому підключіть його у власній гілці разом з app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)Створює DoconutOptions, швидко перевіряє їх (див. DoconutOptions → Перевірка запуску) та реєструє повний граф сервісів:
| Сервіс | Тривалість | Роль |
|---|---|---|
DoconutOptions | Singleton | Об’єкт конфігурації |
| Сервіс кешу сесії | Singleton | Токен → кеш сесії (IMemoryCache також зареєстровано) |
IDoconutLicenseService | Singleton | Ліцензія завантажується один раз під час запуску (пріоритет: LicenseStream → LicenseContent → LicensePath → авто‑пошук) |
| Конвеєр обробки зображень сторінок | Singleton | Виконує обробку зображень сторінок (водяний знак, обертання, масштабування, анотації) |
| Безпека документу (сховище доступу) | Singleton | Надає права для прив’язки токен‑до‑сесії |
Viewer | Transient | Публічний фасад відкриття/закриття |
DocumentConverter | Transient | Фасад конвертації — потребує плагін Converter |
DocumentSigner | Transient | Фасад підпису — потребує плагін Signer (див. Signer Plugin) |
DistributedDocumentPublisher | Transient | Публікує артефакти документу у спільне сховище |
Health check "doconut" | — | Повідомляє стан ліцензії/закінчення терміну через перевірки здоров’я ASP.NET |
У попередній бібліотеці .NET Standard немає еквівалентного виклику. Вона створювала new Viewer(cache, accessor) на кожен запит і передавала параметри в проміжне ПЗ; обидва замінені цією єдиною реєстрацією.
Дві поведінки, які варто знати:
- Converter потребує свій плагін. Отримання
DocumentConverterбезoptions.AddPlugin<ConverterPlugin>()викликає виключення:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner дотримується того ж правила: без options.AddPlugin<SignerPlugin>() він викликає No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- Права плагіна перевіряються під час запуску. Відсутня ліцензія, застарілий файл
TRIALабо платна ліцензія без зареєстрованих можливостей плагіна призводять до помилки під часAddDoconut(). Тимчасові/демо‑реєстрації залишаються активними після дати закінчення, тоді як під час виконання ворота відкликають прострочені можливості.
Перевірка здоров’я інтегрується зі стандартним механізмом ASP.NET Core — налаштуйте її, якщо хочете отримати стан ліцензії на вашому ендпоінті здоров’я:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Додає проміжне ПЗ Doconut для обробки зображень сторінок. Воно обслуговує кожен запит, що містить параметр запиту ?token= — сторінки, мініатюри, пошук, анотації, дії зі сторінками (повна таблиця запитів у Core Concepts → How the Viewer Works) — і відповідає на будь‑який інший запит самостійно за допомогою 404 (або банера ShowDoconutInfo): воно ніколи не передає запит далі по конвеєру. Підключіть його у власній гілці, як у прикладах на цій сторінці. Коли UnsafeMode є false, шар безпеки документу підключається автоматично перед ним.
Він не приймає аргументів. Передача екземпляра DoconutOptions тут була у попередній бібліотеці і більше не компілюється.
Звичайна конфігурація зберігає історичну форму запиту DocImage.axd з гілкою MapWhen (клієнт тоді використовує BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)Обслуговує вбудовані JS, CSS, зображення та шрифти за адресою DoconutOptions.ResourcesPath (за замовчуванням /doconut-res). Це файли, для яких Viewer.ReferenceCss() / ReferenceScripts() генерують теги.
Завжди викликайте його перед UseDoconut(). Якщо область переглядача порожня і консоль браузера показує 404 для /doconut-res/..., цей виклик відсутній або розташований неправильно.
Це підтримувана заміна для ручного підключення проміжного ПЗ обробки вбудованих ресурсів.
Обслуговування зі спільного сховища
Існують ще два реєстрації для розгортань, де вузол, що генерує документ, не обов’язково є вузлом, що обслуговує його сторінки. Обидва варіанти повністю описані у Distributed Deployments; їх сигнатури такі:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // черга публікації у фоні за згодою
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // спільне сховище для завантажень віджетівЧастина читання — це окреме проміжне ПЗ з збірки Doconut.Clouds, яке постачається в тому ж пакеті:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) та WebFarmOptions відсутні у цьому випуску. Дивіться migration guide для покрокового зіставлення параметрів.
Підсумок порядку
app.UseRouting();
app.UseSession(); // викличте UseSession() перед UseDoconut()
app.UseDoconutResources(); // повинно бути зареєстровано перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // або гілка MapWhenЧи була ця сторінка корисною?