DoconutExtensions – Doconut 文档

DoconutExtensions（namespace 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 插件
`DistributedDocumentPublisher`	—	将文档的制品发布到共享存储
Health check `"doconut"`	—	通过 ASP.NET 健康检查报告许可证/过期状态

在之前的 .NET Standard 库中没有等价的调用。它会在每个请求中 new Viewer(cache, accessor) 并将选项传递给中间件；这两者都已被此单一注册取代。

两个值得了解的行为：

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 时，文档安全层会自动在其之前接入。

它不接受任何参数。 在此处传入 DoconutOptions 实例是之前库的用法，现已不再编译。

参考示例通过路径分支路由小部件的请求，保持历史请求形态：

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 错误，则说明此调用缺失或位置不当。

这是手动使用 app.UseMiddleware<EmbeddedResourceMiddleware>() 接入嵌入资源中间件的受支持替代方案。

Serving from shared storage（从共享存储提供服务）

还有两项注册用于部署场景：渲染文档的节点不一定是提供页面的节点。这两者在分布式部署中都有完整覆盖；其签名如下：

text

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // opt-in background publish queue
IServiceCollection AddDoconutDistributedWidgets(...)        // shared backing store for widget uploads

读取端是 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();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)