Doconut扩展

服务和中间件注册

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 → 启动验证),并注册完整的服务图:

ServiceLifetimeRole
DoconutOptionsSingleton配置对象
Session cache serviceSingletonToken → 会话缓存(IMemoryCache 也已注册)
IDoconutLicenseServiceSingleton启动时加载一次的许可证(优先级顺序:LicenseStream → LicenseContent → LicensePath → 自动搜索)
Page-image pipelineSingleton对页面执行图像处理(水印、旋转、缩放、注释)
Document security (access store)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 错误,则说明此调用缺失或位置不当。

从共享存储提供服务

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

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

排序回顾

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

此页面对您有帮助吗?