Doconut扩展

服务和中间件注册

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

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

AddDoconut

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

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

服务生命周期角色
DoconutOptions单例配置对象
IViewerFactory单例映射扩展到格式查看器
IDocumentSessionManager单例Token → 会话缓存（IMemoryCache 也已注册）
IDoconutLicenseService单例许可证在启动时加载一次（优先级：LicenseStream → LicenseContent → LicensePath → 自动搜索）
PageImageService单例页面图像管道（水印/旋转/缩放/注释）
文档安全（访问存储）单例为 token 与会话绑定提供授权
Viewer瞬态公共打开/关闭外观
DocumentConverter瞬态转换外观 — 需要 Converter 插件
健康检查 "doconut"—通过 ASP.NET 健康检查报告许可证/到期状态

两个值得了解的行为：

  • Converter 需要其插件。 解析 DocumentConverter 而没有 options.AddPlugin<ConverterPlugin>() 会抛出：
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= 查询参数的请求——页面、缩略图、搜索、注释、页面操作（完整请求表位于 核心概念 → 查看器工作原理）。当 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();          // 当 UnsafeMode = false 时需要
app.UseDoconutResources(); // 1st Doconut 调用
app.UseDoconut();          // 2nd Doconut 调用 (或通过 MapWhen 分支)

此页面对您有帮助吗？