DoconutExtensions
Регистрация сервисов и middleware
DoconutExtensions (namespace Doconut.Middleware) — это статический класс с тремя вызовами, которые делает каждый хост Doconut: одна регистрация сервиса и две регистрации middleware.
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 → проверка при запуске) и регистрирует полный граф сервисов:
| Service | Lifetime | Role |
|---|---|---|
DoconutOptions | Singleton | Объект конфигурации |
| Сервис кэша сессий | Singleton | Токен → кэш сессии (IMemoryCache также зарегистрирован) |
IDoconutLicenseService | Singleton | Лицензия загружается один раз при запуске (приоритет: LicenseStream → LicenseContent → LicensePath → авто‑поиск) |
| Конвейер обработки страниц и изображений | Singleton | Выполняет обработку изображений страниц (водяной знак, вращение, масштабирование, аннотации) |
| Безопасность документов (хранилище доступа) | Singleton | Предоставляет привязку токен‑к‑сессии |
Viewer | Transient | Публичный фасад открытие/закрытие |
DocumentConverter | Transient | Фасад конвертации — требует плагин Converter |
DocumentSigner | Transient | Фасад подписи — требует плагин Signer (см. Плагин Signer) |
DistributedDocumentPublisher | Transient | Публикует артефакты документа в общее хранилище |
Health check "doconut" | — | Сообщает о состоянии лицензии/срока действия через проверки состояния ASP.NET |
В предыдущей библиотеке .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>().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)Добавляет middleware 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/..., этот вызов отсутствует или расположен неверно.
Это поддерживаемая замена ручной настройки middleware обработки встроенных ресурсов.
Serving from shared storage
Существуют ещё две регистрации для развертываний, где узел, рендерящий документ, не обязательно является узлом, обслуживающим его страницы. Оба случая полностью описаны в Распределённые развертывания; сигнатуры следующие:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // включаемая очередь фоновой публикации
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // общее резервное хранилище для загрузок виджетовЧитательная часть — отдельный middleware из сборки Doconut.Clouds, которая поставляется в том же пакете:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) и WebFarmOptions отсутствуют в этом выпуске. См. руководство по миграции для сопоставления параметр за параметром.
Ordering recap
app.UseRouting();
app.UseSession(); // вызовите UseSession() перед UseDoconut()
app.UseDoconutResources(); // должно быть зарегистрировано перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // или ветка MapIfБыла ли эта страница полезной?