DoconutExtensions

服务和中间件注册

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

csharp
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // 在 UseDoconut() 之前
app.UseDoconut();

添加 Doconut

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

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

服务生命周期角色
DoconutOptions单例配置对象
会话缓存服务单例Token → 会话缓存（IMemoryCache 也已注册）
IDoconutLicenseService单例启动时加载一次的许可证（优先级：LicenseStream → LicenseContent → LicensePath → 自动搜索）
页面图像流水线单例对页面执行图像处理（水印、旋转、缩放、注释）
文档安全（访问存储）单例用于 token 与会话绑定的授权
Viewer瞬态公共的打开/关闭门面
DocumentConverter瞬态转换门面 — 需要 Converter 插件
DistributedDocumentPublisher—将文档的制品发布到共享存储
健康检查 "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");

使用 Doconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

添加 Doconut 页面图像中间件。它会响应所有带有 ?token= 查询参数的请求 — 页面、缩略图、搜索、注释、页面操作（完整请求表见 核心概念 → 查看器工作原理）。当 UnsafeMode 为 false 时，文档安全层会在其之前自动接入。

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

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

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

使用 Doconut 资源

text
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

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

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

这是手动接入嵌入资源处理中间件的受支持替代方案。

从共享存储提供服务

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

text
IServiceCollection AddDoconutDistributedAsyncPublish(...)   // 选择加入的后台发布队列
IServiceCollection AddDoconutDistributedWidgets(...)        // 用于 widget 上传的共享后备存储

读取端是来自 Doconut.Clouds 包的独立中间件：

text
IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

UseDoconutWebFarm(...) 和 WebFarmOptions 在此版本中不存在。请参阅 迁移指南 了解逐项映射。

排序回顾

csharp
app.UseRouting();
app.UseSession();          // 当 UnsafeMode = false 时必需
app.UseDoconutResources(); // 1st Doconut 调用
app.UseDoconut();          // 2nd Doconut 调用（或通过 MapWhen 分支）

此页面对您有帮助吗？