在业务应用中添加文档查看功能不仅仅是把 PDF 放进 iframe。Office 文件、CAD 图纸、电子邮件文件和图像都需要不同的渲染能力，同时应用仍需控制身份验证、存储、授权和保留。

Doconut 是一个 .NET 文档查看器 SDK，旨在将文档渲染和交互嵌入到 Web 应用中。本文不提供未经验证的源码配方，而是解释团队应做出的集成决策，并指出常见的围绕 SDK 的标准 .NET 组件。

为什么嵌入式查看器不同于文件下载

下载端点会传输原始文件，并将查看体验交给应用之外的软件。嵌入式查看器让用户停留在你的产品内部，并能提供统一的导航、搜索、审阅以及其他已启用功能的界面。

自行构建渲染层非常困难，因为每种格式都有各自的规则：

PDF 文件可能包含嵌入字体、批注、表单以及非常大的页数集合。
Word、Excel 和 PowerPoint 文件需要细致的布局和字体处理。
CAD 图纸需要精确的缩放、图层和细致的放大功能。
电子邮件和图像格式会引入附件、元数据、颜色和分辨率等问题。

专用 SDK 让应用团队能够专注于访问控制、工作流和用户体验，而不是为每种受支持的格式维护单独的渲染器。

步骤 1：确认所需的格式和功能

先对用户打开的文件进行真实的清点。将必需的格式与偶尔使用的格式区分开，并记录代表性的样本用于测试。

你的检查清单可能包括：

PDF 和 XPS 文档
文本处理文档
电子表格
演示文稿
CAD 图纸
电子邮件文件
常见图像格式

随后确定每个工作流所需的功能。查看、全文搜索、批注、打印和转换是不同的能力，可能需要不同的 Doconut 组件或授权。

在决定格式或功能之前，请先查看已验证的 Doconut Viewer 页面。产品功能可能会变化，因此你的验收测试应始终是客户实际使用文档的最终依据。

步骤 2：选择文档进入应用的方式

ASP.NET 应用可以从多个受控来源接收文档：

通过 ASP.NET Core IFormFile 处理的上传
受保护的文件位置
数据库或文档管理仓库
服务器访问的对象存储
返回 Stream 的内部服务

查看工作流应使用服务器授权的文档引用。不要在客户端标记中放置存储凭据、无限制的文件路径或永久的公共 URL。

如果用户上传文件，请在渲染前进行验证。检查文件大小、扩展名、文件签名以及任何业务特定的限制。存储服务器生成的标识符，而不是信任原始文件名作为路径。

步骤 3：定义身份验证和授权

应用——而不是查看器 UI——应该决定谁有权打开文档。

在 ASP.NET Core 中，标准机制如身份验证中间件、[Authorize] 特性、策略、声明以及基于资源的授权可以保护启动查看会话的端点。授权决策应同时考虑当前用户和请求的文档。

安全的请求流程如下：

用户使用应用层标识符请求文档。
服务器对用户进行身份验证。
服务器验证用户是否可以访问该特定文档。
服务器解析受保护的存储位置。
查看器仅收到该授权会话所需的信息。

切勿认为隐藏工具栏按钮就是授权控制。即使未显示下载或打印控件，服务器端的访问检查仍然是必需的。

步骤 4：通过官方集成资源添加 Doconut

使用 Doconut 提供的当前包和设置说明。已验证的 Doconut 下载页面提供 NuGet 集成资源、文档、示例和演示。

具体的设置可能取决于：

你的 ASP.NET 或 .NET 应用类型
所选的 Doconut 产品和插件
Doconut 版本
你的许可证
启用的文档格式和功能
Windows 服务器配置

请遵循与已安装版本匹配的文档。避免直接复制与其他博客文章无关的初始化代码片段，因为命名空间、配置、资源路径和 API 在不同版本之间可能会变化。

步骤 5：创建专用的查看边界

将文档查看封装在一个小型应用服务中，而不是在控制器和 UI 组件中随处调用 SDK 功能。

该服务可以负责：

解析已授权的文档标识符
在适当时以受控 Stream 打开文档
提供所需的查看配置
释放文件和流资源
将技术故障转换为安全的应用错误
记录运营指标但不记录文档内容

此边界使升级更容易，并降低将存储细节暴露给表现层的风险。同时也为测试提供了明确的替代实现位置。

步骤 6：设计查看页面

查看器需要足够的空间才能发挥作用。一个被无关控件包围的窄卡片会让大型电子表格和 CAD 图纸难以检查。

围绕以下要点规划页面：

稳定的查看器高度
清晰的加载、空状态和错误状态
简洁的文档标题
可键盘访问的外围控件
不隐藏重要查看器控件的布局
明确的返回父工作流方式

使用长文件名、大页数、宽电子表格、细节图纸以及渲染失败的文档进行测试。错误状态不应泄露服务器路径、异常堆栈或存储 URL。

步骤 7：管理文件和临时数据

在部署前定义保留策略。将原始文件、临时渲染数据、缓存、导出、批注和日志分别考虑。

有用的防护措施包括：

具有受限权限的专用临时目录
唯一的服务器生成名称
成功或失败会话后的清理
对被遗弃的临时文件进行计划任务清理
存储配额和监控
根据安全策略对静止数据进行加密

让清理过程可观测。如果删除失败却未被记录，临时文件会累计，进而成为运营和安全问题。

步骤 8：配置生产环境防护措施

文档渲染会消耗 CPU、内存和临时磁盘空间。通过显式限制来保护应用：

最大上传大小
最大并发渲染作业数
请求和处理超时
异步渲染时的队列限制
临时存储配额
健康检查和结构化错误监控

对于大规模或不可预测的工作负载，建议将渲染与对延迟敏感的业务流程隔离。使用类似客户实际文档的文件进行测量，而不是仅依赖小型测试文件。

步骤 9：测试完整工作流

成功的集成测试应覆盖的不止“第一页出现”。

测试内容包括：

每一种必需的文件格式
小文件、大文件、多页以及损坏的文件
包含不常见字体的文档
当工作流支持时的受密码保护文件
授权用户与未授权用户
并发查看会话
应用重启和请求中断
成功与失败后的清理
在所选产品配置中包含的查看器功能

保留一套已脱敏的版本化测试文档集合。升级 Doconut、.NET、Windows Server、存储基础设施或相关依赖时重新运行这些测试。

安全检查清单

发布前，请确认：

每个查看请求在适当情况下都要求身份验证。
对特定文档执行授权检查。
用户可控输入不能成为无限制的服务器文件路径。
存储凭据绝不泄露到客户端。
已启用上传限制和验证。
临时文件具有受限访问并配有经测试的清理策略。
日志不包含文档内容、机密信息和敏感 URL。
向用户展示的错误信息已被清理。
SDK 与应用依赖遵循更新流程。

查看器控件可以配合业务工作流，但它们无法阻止信息在授权用户可见后被捕获。请将其与访问控制和适当的信息保护策略一起使用。

Doconut 的定位

Doconut 为 .NET 应用提供文档查看能力，而你的应用仍负责身份、授权、文件存储、保留、审计以及周边工作流。

这种职责划分为 .NET 团队提供了一条实用路径，能够在不从头构建多个渲染引擎的情况下支持业务文档。同时，它也确保产品特定的集成细节始终绑定在你部署的官方文档上。

探索 Doconut .NET 文档查看器 SDK，随后使用官方下载和文档资源对自己的文档进行评估。

结论

可靠的嵌入式文档查看器始于明确的格式需求和安全的服务器端文档流。验证输入、授权每一次文档请求、在应用服务后面封装 SDK 访问、规划临时文件清理，并使用真实文件进行测试。

在这些基础之上，Doconut 可以为你的基于 Windows 的 .NET Web 应用提供查看层，而你的团队则保持对应用架构和文档生命周期的全面控制。