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(添加 Doconut)

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

构建 DoconutOptions,快速失败地验证它们(参见 DoconutOptions → 启动验证),并注册完整的服务图:

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

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

有两种值得了解的行为:

  • Converter 需要其插件。 Resolving DocumentConverter without options.AddPlugin<ConverterPlugin>() throws:
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(使用 Doconut)

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

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

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

常见的设置保留了历史的 DocImage.axd 请求形态,并使用 MapWhen 分支(客户端随后使用 BasePath: '/'):

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

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

从共享存储提供服务

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

text
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null)   // 选择加入后台发布队列
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure)                     // 用于 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();          // 在使用 UseDoconut() 之前调用 UseSession()
app.UseDoconutResources(); // 必须在 UseDoconut() 之前注册
app.Map("/doconut", branch => branch.UseDoconut()); // 或一个 MapWhen 分支

此页面对您有帮助吗?