DoconutExtensions

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

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

AddDoconut

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

Создаёт DoconutOptions, быстро проверяет их корректность (см. DoconutOptions → Startup validation) и регистрирует полный граф сервисов:

В предыдущей библиотеке .NET Standard аналогичного вызова не было. Там для каждого запроса создавался new Viewer(cache, accessor) и параметры передавались middleware; оба эти шага заменены единой регистрацией.

Два поведения, о которых стоит знать:

• Converter требует своего плагина. Попытка разрешить DocumentConverter без options.AddPlugin<ConverterPlugin>() приводит к исключению:

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

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

Проверка состояния интегрируется со стандартным механизмом ASP.NET Core — добавьте её, если хотите видеть состояние лицензии в эндпоинте здоровья:

app.MapHealthChecks("/health");

UseDoconut

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Добавляет middleware для обработки изображений страниц Doconut. Он отвечает на каждый запрос, содержащий параметр ?token= — страницы, миниатюры, поиск, аннотации, действия со страницами (полная таблица запросов находится в Core Concepts → How the Viewer Works). Когда UnsafeMode равно false, слой безопасности документа автоматически подключается перед ним.

Он не принимает аргументов. Передача здесь экземпляра DoconutOptions была характерна для предыдущей библиотеки и теперь не компилируется.

В примере ссылки запросы виджета направляются через ветвление пути, сохраняя историческую форму запросов:

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/..., значит этот вызов отсутствует или расположен неверно.

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

Serving from shared storage

Две дополнительные регистрации нужны для развертываний, где узел, рендерящий документ, не обязательно является узлом, обслуживающим его страницы. Оба сценария полностью описаны в Распределённые развертывания; сигнатуры следующие:

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

Часть чтения реализована отдельным middleware из пакета Doconut.Clouds:

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

UseDoconutWebFarm(...) и WebFarmOptions в этом выпуске отсутствуют. См. руководство по миграции для сопоставления параметров шаг за шагом.

Ordering recap

app.UseRouting();
app.UseSession();          // требуется, когда UnsafeMode = false
app.UseDoconutResources(); // первый вызов Doconut
app.UseDoconut();          // второй вызов Doconut (или через ветвление MapWhen)