DoconutExtensions – Doconut 文档

DoconutExtensions (namespace Doconut.Middleware) 是所有 Doconut 主机都会调用的静态类，提供三个调用：一次服务注册和两次中间件注册。

csharp

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

AddDoconut 方法

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 方法

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 方法

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)