DoconutExtensions – Doconut 文档

DoconutExtensions（命名空间 Doconut.Middleware）是一个静态类，提供每个 Doconut 主机必须的三个调用：一次服务注册和两次中间件注册。

csharp

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

AddDoconut（添加 Doconut）

text

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

构建 DoconutOptions，快速失败地验证它们（参见 DoconutOptions → 启动验证），并注册完整的服务图：

服务	生命周期	角色
`DoconutOptions`	Singleton	配置对象
`IViewerFactory`	Singleton	将扩展映射到格式查看器
`IDocumentSessionManager`	Singleton	Token → 会话缓存（`IMemoryCache` 也已注册）
`IDoconutLicenseService`	Singleton	启动时加载一次许可证（优先级：`LicenseStream` → `LicenseContent` → `LicensePath` → 自动搜索）
`PageImageService`	Singleton	页面图像流水线（水印/旋转/缩放/注释）
Document security (access store)	Singleton	用于 token 与会话绑定的授权
`Viewer`	Transient	公开的打开/关闭外观
`DocumentConverter`	Transient	转换外观 — 需要 Converter 插件
Health check `\"doconut\"`	—	通过 ASP.NET 健康检查报告许可证/过期状态

两个值得了解的行为：

Converter 需要其插件。 在未使用 options.AddPlugin<ConverterPlugin>() 的情况下解析 DocumentConverter 会抛出：

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（使用 Doconut）

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

添加 Doconut 页面图像中间件。它会响应所有带有 ?token= 查询参数的请求 —— 页面、缩略图、搜索、注释、页面操作（完整请求表见 Core Concepts → How the Viewer Works）。当 UnsafeMode 为 false 时，文档安全层会在此之前自动接入。

参考示例通过路径分支路由小部件的请求：

csharp

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources（使用 Doconut 资源）

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

在 DoconutOptions.ResourcesPath（默认 /doconut-res）提供嵌入的 JS、CSS、图像和字体。这些文件是 Viewer.ReferenceCss() / ReferenceScripts() 所生成标签所指向的资源。

始终在 UseDoconut() 之前调用它。 如果查看器区域保持空白且浏览器控制台显示 /doconut-res/... 的 404 错误，则说明此调用缺失或位置不当。

调用顺序回顾

csharp

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)