使用 Doconut 实现文档管理

在 .NET 门户中，文档管理 工作流通常需要三件事：

1. 一种无需从头编写查看器即可加载 PDF、Office 文件、CAD 图纸或图像的方法。
2. 一个将已加载文档绑定到当前浏览器会话的安全令牌。
3. 一个在用户完成后立即释放内存的清理步骤。

Doconut 通过单个 Viewer 服务、轻量级的 IMemoryCache 会话以及显式的 CloseDocument 调用提供了全部三项功能。

---

1. 在 DI 容器中注册查看器

在应用程序启动期间，通过调用官方文档中描述的 Doconut 注册方法，将 Doconut 服务添加到 DI 容器中。此步骤会注册查看器、许可证处理以及用于保存文档会话的内存缓存。

注册会在启动时验证许可证，因此任何缺失或无效的许可证都会快速失败，让您在第一个请求到达服务器之前就发现问题。

---

2. 插入提供页面图像、缩略图和注释数据的中间件

在请求管道中配置 Doconut 中间件，使任何包含 ?token= 查询字符串的请求都由 Doconut 处理。当 UnsafeMode 为 false（默认值）时，中间件会强制使用默认安全标记（secure-{token}），并提供页面图像、缩略图和注释数据。

将中间件放置在专用分支上可保持其余管道不受影响，并且在无需粘性会话的情况下实现水平扩展。

---

3. 打开文档并获取不透明的会话令牌

创建一个接收文件路径（或流）并返回令牌的单一端点。该令牌是客户端小部件唯一能看到的凭证。

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // 令牌是不透明的 — 将其交给小部件，切勿记录或持久化它。
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

OpenDocumentAsync 内部发生了什么

1. 许可证检查 – 无效许可证会立即抛出 LicenseException。
2. 会话创建 – Doconut 选择合适的格式查看器（PDF、Word、DWG，…），并在 IMemoryCache 中使用 GUID 令牌存储引擎。
3. 安全注册 – 使用 UnsafeMode = false，令牌通过 secure-{token} 标记绑定到调用者的 ASP.NET 会话。只有该浏览器会话能够请求页面。
4. 令牌返回 – 客户端收到令牌后，在每个后续请求中使用它（/DocImage.axd?token=…）。

默认的滑动过期时间为 60 分钟（可通过 DocOptions.TimeOut 配置）。每次页面请求都会重置计时器，因此空闲会话会自动消失。

---

4. 在客户端渲染文档

在浏览器中调用端点，获取令牌并将其交给 Doconut 小部件：

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // 由 Doconut 提供的 JavaScript 小部件
    });

小部件内部会发出页面、缩略图、搜索和注释请求，所有请求都包含相同的 token。由于令牌绑定到服务器端会话，恶意用户无法劫持其他用户的文档。

---

5. 当用户离开查看器时立即关闭文档

对于大型 PDF 或 CAD 文件，您应立即释放渲染引擎。可从服务器端端点或小部件的 “unload” 事件中调用 CloseDocument。

// 服务器端端点
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// 来自小部件的直接调用（如果你将令牌暴露给后端）
viewer.CloseDocument(token);

CloseDocument 从缓存中移除会话，释放底层文档引擎，删除 secure-{token} 标记，并撤销访问授权。滑动过期最终也会实现相同效果，但显式关闭可确保在用户完成的瞬间回收内存。

---

6. 可选：在服务器上转换文档

如果工作流需要将上传的 Word 文件导出为 PDF，请在 Doconut 配置中启用 Converter 插件（参见文档）。插件注册后，您可以注入 DocumentConverter 并调用其 ConvertAsync 方法。转换在服务器上执行，因此无需在 Web 服务器上安装 Office。

---

7. 企业级文档管理的扩展考虑因素

• 无状态前端 – 查看器小部件从不持有文档数据；所有繁重的处理都在服务器端完成。
• 分布式缓存 – 如果运行多个 Web 农场节点，可将默认的内存缓存替换为分布式提供程序（Redis、NCache）。由于中间件从配置的 IMemoryCache 读取，令牌到会话的映射保持不变。
• 后台任务 – 您可以在后台工作者中预先打开文档，缓存令牌并稍后交给 UI。请记住，每个令牌在会话中只能使用一次；若要复用，需要重新调用 OpenDocumentAsync。

这些模式使您能够构建一个 文档管理 平台，该平台可从单服务器内部网门户扩展到多区域云服务，而无需重写查看器逻辑。

---

8. 生产就绪实现的快速检查清单

步骤	操作
1	在 Program.cs 中注册 Doconut 服务（验证许可证）。
2	在专用分支上添加 Doconut 中间件。
3	公开一个调用 OpenDocumentAsync 的 /api/open 端点。
4	在客户端将返回的令牌传递给 objViewer.View(token)。
5	当查看器隐藏或页面卸载时调用 CloseDocument(token)。
6	（可选）如果需要服务器端转换，启用 ConverterPlugin。
7	（可选）将 IMemoryCache 替换为分布式缓存以实现水平扩展。

遵循此清单，您即可拥有基于 Doconut 原生 .NET 查看器的完整、安全、高性能 文档管理 流程。