DoconutExtensions

服务和中间件注册

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

csharp
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession();          // 在调用 UseDoconut() 之前调用 UseSession()
app.UseDoconutResources(); // 必须在 UseDoconut() 之前注册
app.Map("/doconut", branch => branch.UseDoconut());

UseDoconut() 会响应所有到达它的请求,因此请使用 app.Map 将其挂载在独立的分支上。

AddDoconut

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

构建 DoconutOptions,对其进行快速失败验证(参见 DoconutOptions → Startup validation),并注册完整的服务图:

服务生命周期角色
DoconutOptionsSingleton配置对象
会话缓存服务SingletonToken → 会话缓存(IMemoryCache 也已注册)
IDoconutLicenseServiceSingleton启动时加载一次的许可证(优先级顺序:LicenseStream → LicenseContent → LicensePath → 自动搜索)
页面图像管道Singleton对页面执行图像处理(水印、旋转、缩放、注释)
文档安全(访问存储)Singleton用于 token 与会话绑定的授权
ViewerTransient公共的打开/关闭门面
DocumentConverterTransient转换门面 — 需要 Converter 插件
DocumentSignerTransient签名门面 — 需要 Signer 插件(参见 签名插件)
DistributedDocumentPublisherTransient将文档的制品发布到共享存储(参见 分布式部署)
Health check "doconut"—通过 ASP.NET 健康检查报告许可证/过期状态

两个值得了解的行为:

  • Converter 需要其插件。 解析 DocumentConverter 而没有 options.AddPlugin<ConverterPlugin>() 会抛出:
text
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentSigner 遵循相同规则:没有 options.AddPlugin<SignerPlugin>() 时会抛出 No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().

  • 插件授权在启动时进行验证。 缺少许可证、旧版 TRIAL 文件,或付费许可证但缺少已注册插件的能力,都会在 AddDoconut() 时失败。临时/演示注册在其过期日期后仍然有效,而运行时门控会撤销已过期的能力。

健康检查集成到标准的 ASP.NET Core 机制中 — 如果希望在健康端点上获取许可证状态,请映射它:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

添加 Doconut 页面图像中间件。它会处理所有带有 ?token= 查询参数的请求——页面、缩略图、搜索、注释、页面操作(完整请求表见 Core Concepts → How the Viewer Works)——并对其他所有请求直接返回 404(或 ShowDoconutInfo 横幅):它永不将请求传递给管道的其余部分。请像本页示例那样将其挂载在独立的分支上。当 UnsafeMode 为 false 时,文档安全层会自动在其前面接入。

一种常见的替代方案是使用 MapWhen 分支保持历史的 DocImage.axd 请求形状(客户端随后使用 BasePath: '/'):

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

Serving from shared storage

对于渲染文档的节点不一定是提供页面的节点的部署场景,还存在另外两种注册方式。两者均在 分布式部署 中有完整说明;其签名如下:

text
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null)   // 可选的后台发布队列
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure)                     // 用于小部件上传的共享后备存储

读取端是来自 Doconut.Clouds 程序集的独立中间件,随同同一包一起发布:

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

Ordering recap

csharp
app.UseRouting();
app.UseSession();          // 在调用 UseDoconut() 之前调用 UseSession()
app.UseDoconutResources(); // 必须在 UseDoconut() 之前注册
app.Map("/doconut", branch => branch.UseDoconut()); // 或 MapWhen 分支

此页面对您有帮助吗?