DoconutExtensions
服务和中间件注册
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
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)构建 DoconutOptions,对其进行快速失败验证(参见 DoconutOptions → Startup validation),并注册完整的服务图:
| 服务 | 生命周期 | 角色 |
|---|---|---|
DoconutOptions | Singleton | 配置对象 |
| 会话缓存服务 | Singleton | Token → 会话缓存(IMemoryCache 也已注册) |
IDoconutLicenseService | Singleton | 启动时加载一次的许可证(优先级顺序:LicenseStream → LicenseContent → LicensePath → 自动搜索) |
| 页面图像管道 | Singleton | 对页面执行图像处理(水印、旋转、缩放、注释) |
| 文档安全(访问存储) | Singleton | 用于 token 与会话绑定的授权 |
Viewer | Transient | 公共的打开/关闭门面 |
DocumentConverter | Transient | 转换门面 — 需要 Converter 插件 |
DocumentSigner | Transient | 签名门面 — 需要 Signer 插件(参见 签名插件) |
DistributedDocumentPublisher | Transient | 将文档的制品发布到共享存储(参见 分布式部署) |
Health check "doconut" | — | 通过 ASP.NET 健康检查报告许可证/过期状态 |
两个值得了解的行为:
- Converter 需要其插件。 解析
DocumentConverter而没有options.AddPlugin<ConverterPlugin>()会抛出:
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
IApplicationBuilder UseDoconut(this IApplicationBuilder app)添加 Doconut 页面图像中间件。它会处理所有带有 ?token= 查询参数的请求——页面、缩略图、搜索、注释、页面操作(完整请求表见 Core Concepts → How the Viewer Works)——并对其他所有请求直接返回 404(或 ShowDoconutInfo 横幅):它永不将请求传递给管道的其余部分。请像本页示例那样将其挂载在独立的分支上。当 UnsafeMode 为 false 时,文档安全层会自动在其前面接入。
一种常见的替代方案是使用 MapWhen 分支保持历史的 DocImage.axd 请求形状(客户端随后使用 BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)在 DoconutOptions.ResourcesPath(默认 /doconut-res)提供嵌入的 JS、CSS、图像和字体。这些文件是 Viewer.ReferenceCss() / ReferenceScripts() 用于生成标签的。
始终在 UseDoconut() 之前调用它。 如果查看器区域保持为空且浏览器控制台显示 /doconut-res/... 的 404 错误,则说明此调用缺失或放错位置。
Serving from shared storage
对于渲染文档的节点不一定是提供页面的节点的部署场景,还存在另外两种注册方式。两者均在 分布式部署 中有完整说明;其签名如下:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // 可选的后台发布队列
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // 用于小部件上传的共享后备存储读取端是来自 Doconut.Clouds 程序集的独立中间件,随同同一包一起发布:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerOrdering recap
app.UseRouting();
app.UseSession(); // 在调用 UseDoconut() 之前调用 UseSession()
app.UseDoconutResources(); // 必须在 UseDoconut() 之前注册
app.Map("/doconut", branch => branch.UseDoconut()); // 或 MapWhen 分支此页面对您有帮助吗?