DoconutExtensions

Регистрация сервисов и middleware

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

csharp
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession();          // вызовите UseSession() перед UseDoconut()
app.UseDoconutResources(); // должно быть зарегистрировано перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

UseDoconut() отвечает на каждый запрос, который к нему поступает, поэтому смонтируйте его в отдельной ветке с app.Map.

AddDoconut

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

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

ServiceLifetimeRole
DoconutOptionsSingletonОбъект конфигурации
Сервис кэша сессийSingletonТокен → кэш сессии (IMemoryCache также зарегистрирован)
IDoconutLicenseServiceSingletonЛицензия загружается один раз при запуске (приоритет: LicenseStream → LicenseContent → LicensePath → авто‑поиск)
Конвейер обработки страниц и изображенийSingletonВыполняет обработку изображений страниц (водяной знак, вращение, масштабирование, аннотации)
Безопасность документов (хранилище доступа)SingletonПредоставляет привязку токен‑к‑сессии
ViewerTransientПубличный фасад открытие/закрытие
DocumentConverterTransientФасад конвертации — требует плагин Converter
DocumentSignerTransientФасад подписи — требует плагин Signer (см. Плагин Signer)
DistributedDocumentPublisherTransientПубликует артефакты документа в общее хранилище
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>().

DocumentSigner следует тому же правилу: без options.AddPlugin<SignerPlugin>() он бросает No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().

  • Права плагина проверяются при запуске. Отсутствующая лицензия, устаревший файл 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) — и отвечает на любые другие запросы сам с помощью 404 (или баннера ShowDoconutInfo): он никогда не передаёт запрос дальше по конвейеру. Смонтируйте его в отдельной ветке, как в примерах на этой странице. Когда UnsafeMode находится в состоянии false, слой безопасности документа автоматически подключается перед ним.

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

Обычная настройка сохраняет историческую форму запроса DocImage.axd с веткой MapWhen (клиент затем использует BasePath: '/'):

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(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null)   // включаемая очередь фоновой публикации
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure)                     // общее резервное хранилище для загрузок виджетов

Читательная часть — отдельный 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();          // вызовите UseSession() перед UseDoconut()
app.UseDoconutResources(); // должно быть зарегистрировано перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // или ветка MapIf

Была ли эта страница полезной?