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 → Проверка запуска) и регистрирует полный граф сервисов:

СервисВремя жизниРоль
DoconutOptionsSingletonОбъект конфигурации
Session cache serviceSingletonToken → кэш сессии (IMemoryCache также зарегистрирован)
IDoconutLicenseServiceSingletonЛицензия загружается один раз при запуске (приоритет: LicenseStream → LicenseContent → LicensePath → авто‑поиск)
Page-image pipelineSingletonВыполняет обработку изображений страниц (водяной знак, вращение, масштабирование, аннотации)
Document security (access store)SingletonПредоставляет привязку токена к сессии
ViewerTransientПубличный фасад открытие/закрытие
DocumentConverterTransientФасад конвертации — требует плагин Converter
DocumentSignerTransientФасад подписи — требует плагин Signer (см. Плагин Signer)
DistributedDocumentPublisherTransientПубликует артефакты документа в общие хранилища (см. Распределённые развертывания)
Health check "doconut"—Отчёт о состоянии лицензии/срока действия через проверки состояния ASP.NET

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

  • 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 — добавьте её, если хотите состояние лицензии на вашем endpoint проверки здоровья:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

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

Распространённая альтернатива сохраняет историческую форму запроса 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/..., этот вызов отсутствует или размещён неверно.

Обслуживание из общего хранилища

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

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

Сводка порядка

csharp
app.UseRouting();
app.UseSession();          // вызовите UseSession() перед UseDoconut()
app.UseDoconutResources(); // должен быть зарегистрирован перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // или ветка MapWhen

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