查看器如何工作

文档请求生命周期

Doconut 将文档渲染为通过 ASP.NET Core 中间件提供的分页图像。了解整个生命周期——打开、令牌、页面请求、关闭——可以解释几乎所有你会观察到的行为,包括错误信息。

三个关键组成部分

  • Viewer — 你注入的公共服务。它打开文档并返回会话令牌。
  • 文档会话 — 一个服务器端对象,保存已加载的文档,以 IMemoryCache 中的令牌为键。
  • Doconut 中间件 — 由 UseDoconut() 添加;响应浏览器小部件发出的每个请求(pages、thumbnails、search、annotations,…),始终通过令牌进行身份验证。

Viewer 是无状态的 —— 设计如此

Viewer 是密封的,不保留每个请求的文档状态,并且刻意 不 实现 IDisposable。会话独立存在于会话管理器中,并通过缓存过期或显式的 CloseDocument(token) 进行清理。

你不再需要自行实例化它。AddDoconut() 将其注册为瞬态服务;在需要的地方注入它:

csharp
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

在 MVC 应用程序中,将其作为构造函数参数;在 Razor 视图中,使用 @inject Doconut.Viewer Viewer。对 Viewer 实例的应用程序级缓存已不再需要 —— 也不再正确,因为它们不保存任何值得缓存的内容。

OpenDocumentAsync 内部发生了什么

  1. 许可证检查。 被拒绝或版本过期的许可证(列入黑名单、被篡改,或构建时间超出许可证的更新窗口)会立即抛出 LicenseException,并将拒绝原因作为消息——对于无效(而非缺失)许可证,打开操作永不静默降级。日历过期的临时或订阅许可证是例外:它不会抛出,而是降级为水印。
  2. 会话创建。 查看器工厂根据文件扩展名挑选合适的格式查看器并加载文档(参见 Rendering Pipeline)。会话被存储在 IMemoryCache 中,使用新生成的 GUID 令牌,并设有 滑动过期 —— DocOptions.TimeOut 分钟,默认 60。每次页面请求都会重置计时。
  3. 安全注册。 使用 UnsafeMode = false(默认),令牌绑定到调用者的 ASP.NET 会话:在会话中写入 secure-{token} 标记,只有打开文档的浏览器会话才能请求其页面。
  4. 返回令牌。 它是随后所有操作的唯一凭证。

没有单独的预热步骤。之前的库提供了 InitCache() 来实现此目的;它已不再存在,也没有任何替代品。

这三个重载唯一的区别在于输入:文件路径、带有每种格式配置的文件路径(PdfConfig、WordConfig,…),或者 Stream 加上根据扩展名决定格式检测的 FileInfo。

小部件如何获取页面

客户端小部件在查询字符串中携带令牌调用 Doconut 中间件。中间件的行为取决于请求类型:

查询用途
?token=…&page=N渲染的页面图像(PNG)
?token=…&page=N&thumb=1缩略图
?token=…&zoom=…放大页面渲染
?token=…&search=term全文搜索(受许可证限制)
?token=…&bookmarks文档大纲/书签
?token=…&copy / &showlinks / &fileFormat文本复制、超链接和格式信息
?token=…&metaDICOM 技术元数据;为此包上的 DICOM 会话返回 501
?token=…&action=rotate/flip/close页面操作和显式关闭
?token=…&AnnSave=… / &AnnLoad保存/加载批注

这些路径在处理之前都会先进行验证:

  • 无令牌 → 中间件返回 404(或在 ShowDoconutInfo = true 时返回版本横幅)。
  • 未知或已过期的令牌 → 返回带有 Document session not found. Please re-open document. 的错误图像。
  • 缺少会话中间件(使用 UnsafeMode = false)→ 返回 HTTP 500,携带 Session middleware not configured. Call UseSession() before UseDoconut().。
  • 令牌由不同的浏览器会话打开 → 返回带有 You Are Not Authorized To View This Page. 的错误图像。

中间件的挂载位置

UseDoconut() 响应携带令牌的请求,无论你将其挂载在哪里。常见的设置是在 MapWhen 分支上保持历史的 DocImage.axd 请求形态,这样已有客户端仍然调用原来的 URL。无论你选择何种方式,客户端的 BasePath 必须与之匹配 —— 参见 ViewerConfig。

从共享存储而非打开节点提供页面是一种完全不同的部署方式;参见 Distributed Deployments。

关闭文档

csharp
viewer.CloseDocument(token);

CloseDocument 将会话从缓存中移除(这会立即释放底层文档引擎并释放其内存),删除 secure-{token} 标记,并撤销访问授权。调用它是可选的——滑动过期会自动进行相同的清理——但对于大文档来说,这是在用户完成后立即释放内存的礼貌做法。

它在注入的 Viewer 上调用。之前的模式——在 using 块中构造一个短暂的 Viewer 仅用于关闭令牌——已没有对应实现,也不再需要。

要点

  • 一个打开的文档 = 一个会话 = 一个令牌。令牌属于每个浏览器会话,而非全局 URL。
  • 令牌在滑动窗口内过期;如果查看器在超过 DocOptions.TimeOut 后仍保持空闲,需要重新打开。
  • Viewer 可以被注入并自由共享;会话携带所有状态。

此页面对您有帮助吗?