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

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

csharp

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // ПЕРЕД UseDoconut()
app.UseDoconut();

AddDoconut

text

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

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

Сервис	Время жизни	Роль
`DoconutOptions`	Singleton	Объект конфигурации
Сервис кэша сессий	Singleton	Token → кэш сессий (`IMemoryCache` также зарегистрирован)
`IDoconutLicenseService`	Singleton	Лицензия загружается один раз при запуске (приоритет: `LicenseStream` → `LicenseContent` → `LicensePath` → авто‑поиск)
Конвейер обработки изображений страниц	Singleton	Выполняет обработку изображений страниц (водяной знак, вращение, масштабирование, аннотации)
Безопасность документа (хранилище доступа)	Singleton	Предоставляет привязку токена к сессии
`Viewer`	Transient	Публичный фасад открытие/закрытие
`DocumentConverter`	Transient	Фасад конвертации — требует плагин Converter
`DistributedDocumentPublisher`	—	Публикует артефакты документа в общее хранилище
Health check `"doconut"`	—	Отчитывается о состоянии лицензии/срока действия через проверки здоровья 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 — добавьте её, если хотите видеть состояние лицензии на вашем эндпоинте здоровья:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Добавляет middleware 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/..., этот вызов отсутствует или находится в неправильном месте.

Это поддерживаемая замена ручной настройки 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(); // 1‑й вызов Doconut
app.UseDoconut();          // 2‑й вызов Doconut (или через ветку MapWhen)