Doconut扩展
服务和中间件注册
DoconutExtensions(命名空间 Doconut.Middleware)是每个 Doconut 主机都会使用的静态类,提供三个调用:一次服务注册和两次中间件注册。
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // 在使用 UseDoconut() 之前调用 UseSession()
app.UseDoconutResources(); // 必须在 UseDoconut() 之前注册
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() 响应所有到达的请求,因此请使用 app.Map 将其挂载在单独的分支上。
AddDoconut(添加 Doconut)
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)构建 DoconutOptions,快速失败地验证它们(参见 DoconutOptions → 启动验证),并注册完整的服务图:
| 服务 | 生命周期 | 角色 |
|---|---|---|
DoconutOptions | Singleton | 配置对象 |
| 会话缓存服务 | Singleton | Token → 会话缓存(IMemoryCache 也已注册) |
IDoconutLicenseService | Singleton | 启动时加载一次的许可证(优先级顺序:LicenseStream → LicenseContent → LicensePath → 自动搜索) |
| 页面图像管道 | Singleton | 对页面执行图像处理(水印、旋转、缩放、注释) |
| 文档安全(访问存储) | Singleton | 用于 token 与会话绑定的授权 |
Viewer | Transient | 公共的打开/关闭门面 |
DocumentConverter | Transient | 转换门面 — 需要 Converter 插件 |
DocumentSigner | Transient | 签名门面 — 需要 Signer 插件(参见 签名插件) |
DistributedDocumentPublisher | Transient | 将文档的产物发布到共享存储 |
健康检查 "doconut" | — | 通过 ASP.NET 健康检查报告许可证/到期状态 |
在之前的 .NET Standard 库中没有等价的调用。它在每个请求中构造 new Viewer(cache, accessor) 并将选项传递给中间件;这两者都被此单一注册所取代。
有两种值得了解的行为:
- Converter 需要其插件。 Resolving
DocumentConverterwithoutoptions.AddPlugin<ConverterPlugin>()throws:
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 机制集成 — 如果希望在健康端点上显示许可证状态,请映射它:
app.MapHealthChecks("/health");UseDoconut(使用 Doconut)
IApplicationBuilder UseDoconut(this IApplicationBuilder app)添加 Doconut 页面图像中间件。它会处理所有带有 ?token= 查询参数的请求——页面、缩略图、搜索、注释、页面操作(完整请求表位于 Core Concepts → How the Viewer Works)——并对其他任何请求自行响应 404(或 ShowDoconutInfo 横幅):它永不将请求传递给管道的其余部分。将其挂载在单独的分支上,如本页示例所示。当 UnsafeMode 为 false 时,文档安全层会在其之前自动接入。
它不接受任何参数。 在此传递 DoconutOptions 实例是之前库的用法,但现在已无法编译。
常见的设置保留了历史的 DocImage.axd 请求形态,并使用 MapWhen 分支(客户端随后使用 BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources(使用 Doconut 资源)
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)在 DoconutOptions.ResourcesPath(默认 /doconut-res)提供嵌入的 JS、CSS、图像和字体。这些文件是 Viewer.ReferenceCss() / ReferenceScripts() 用于生成标签的文件。
始终在 UseDoconut() 之前调用它。 如果查看器区域保持为空且浏览器控制台显示 /doconut-res/... 的 404 错误,则说明此调用缺失或位置错误。
这是手动接入嵌入资源处理中间件的受支持替代方案。
从共享存储提供服务
对于渲染文档的节点不一定是提供页面的节点的部署场景,还存在另外两种注册方式。两者在 分布式部署 中有完整说明;其签名如下:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // 选择加入后台发布队列
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // 用于 widget 上传的共享后备存储读取端是来自 Doconut.Clouds 程序集的独立中间件,随同同一软件包一起提供:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) 和 WebFarmOptions 在此版本中不存在。请参阅 迁移指南 了解逐项设置的映射。
顺序回顾
app.UseRouting();
app.UseSession(); // 在使用 UseDoconut() 之前调用 UseSession()
app.UseDoconutResources(); // 必须在 UseDoconut() 之前注册
app.Map("/doconut", branch => branch.UseDoconut()); // 或一个 MapWhen 分支此页面对您有帮助吗?