查看器如何工作

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

三个关键部件

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

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

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

在需要的地方注入它：

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

OpenDocumentAsync 内部发生了什么

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

这三种重载仅在输入上不同：文件路径、带有每种格式配置的文件路径（PdfConfig、WordConfig，…），或 Stream 加上一个根据扩展名决定格式检测的 FileInfo。

小部件如何获取页面

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

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

• 没有令牌 → 中间件返回 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. 的错误图片。

关闭文档

viewer.CloseDocument(token);

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

要点

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