您将在 .NET 应用中拥有自托管、闪电般快速的文档查看器
通过本指南，您可以在浏览器中直接打开 PDF、Office 文件、CAD 图纸以及其他数十种格式，加载时间亚秒级，无需外部 SaaS 调用，且完全掌控安全性。
前置条件
| 您需要的内容 | 为什么重要 |
|---|---|
| .NET 6 或更高版本（SDK 目标为 .NET 6+） | 确保与 Online Document Viewer SDK 的兼容性 |
| 可运行应用的 Windows 或 Linux 服务器（本地或私有云） | 自托管需要查看器运行在您自己的基础设施中 |
| 能访问 Online Document Viewer NuGet 源（https://doconut.com） | SDK 通过 NuGet 包分发 |
| 基本的 ASP.NET Core 与前端 JavaScript 知识 | 您需要提供返回签名 URL 的端点，并在浏览器中启动查看器 |
| 用于存放源文件的存储位置（文件系统、Blob 存储等） | 查看器从本地或网络路径读取文件，服务器进程必须能够访问该路径 |
缺少上述任意项都会导致构建在第一行代码执行前卡住。
安装 Online Document Viewer SDK
在 Visual Studio 或您喜欢的 IDE 中打开解决方案，并通过 NuGet 管理器添加官方 SDK：
dotnet add package Doconut.NET8
该包包含渲染引擎、格式转换器以及提供生成页面的轻量 HTTP 层。由于 SDK 编译进您的应用，运行时不会调用外部服务。
恢复包后，在 Program.cs（或旧模板的 Startup.cs）中注册 SDK 服务。注册会将渲染管道注入 ASP.NET Core 的 DI 容器，使其在控制器中可用。
为所需格式配置渲染管道
查看器开箱即支持 50 多种格式，包括：
- PDF、DOC、DOCX、ODT、RTF
- XLS、XLSX、CSV、ODS
- PPT、PPTX、ODP
- DWG、DXF、DGN（CAD）
- PSD、SVG、TIFF、WEBP、ICO
- EML、MSG、EPUB、MOBI、MPP、VSD
当请求到达时，SDK 会判断文件类型并选择相应的转换器。为获得最佳性能，请启用内置缓存层，将渲染后的页面存入内存直至请求结束；这正是实现“闪电般快速 – 即时文档渲染并具备优化性能和亚秒级加载”体验的关键。
在控制器中，调用 SDK 的渲染方法（如 RenderAsync），并传入源文件的绝对路径。该方法返回包含基于 canvas 的查看器的 HTML 片段。由于渲染在服务器完成，客户端仅收到可直接显示的标记，从而消除繁重的客户端处理。
使用基于令牌的 URL 与可选限制来保护查看器
数据主权和 GDPR 合规是本地部署的常见顾虑。SDK 与 ASP.NET Core 的身份验证系统集成，允许您生成签名令牌，以一次性授权访问特定文档。
典型流程：
- 前端向您的 API 请求预览令牌，并提供文档标识符。
- API 验证用户权限，创建包含文件路径和过期时间戳的 JWT 样式令牌，并返回该令牌。
- 前端将令牌附加到查看器 URL（例如
/viewer?token=…）。SDK 在每次请求时验证令牌，拒绝被篡改或已过期的令牌。
如果需要阻止用户下载或打印文档，可在 SDK 提供的渲染选项中禁用相应功能。查看器的 JavaScript 层随后会隐藏下载按钮、抑制打印快捷键，并屏蔽右键上下文菜单。
验证一切是否正常
- 访问托管查看器的页面。
- 文档应在一秒内出现，并带有滚动条、缩放控制和搜索框。
- 若已配置禁用下载，“下载”按钮应被隐藏。
- 右键单击文档时不应弹出浏览器上下文菜单（在启用该限制的情况下）。
- 令牌过期后（默认 5 分钟），刷新页面应返回 “401 Unauthorized” 错误，证明令牌验证已生效。
如果上述任意检查未通过，请回顾对应步骤：缺少 SDK 注册、令牌生成错误或安全标志遗漏。