渲染管线

在 OpenDocumentAsync 与到达浏览器的 PNG 之间存在两个不同的阶段：查看器解析（哪个引擎加载文档，在打开时决定一次）和页面处理（每次请求 DocImage.axd 时对每个页面图像的处理）。了解这两者可以解释为何某种格式会以特定方式渲染——以及 DefaultRender 实际上切换了什么。

阶段 1 — 解析格式查看器

工厂通过格式目录将文件扩展名映射到查看器，具有以下三层优先级：

1. 自定义查看器优先。 任何使用 DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) 注册的查看器都会覆盖所有内置查看器。
2. 内置系列查看器。 目录将每个可查看的扩展名映射到一个查看器系列——Word、Excel、PowerPoint、Pdf、Cad、Dgn、Image、Tiff、Psd、Email、Visio、Project、Xps、Epub、Txt、Html、Mht、Dcn——每个系列都有自己的引擎适配器。如果已授权的插件为相同扩展名提供了查看器，插件的查看器会替代内置的。
3. 仅插件支持的格式。 某些扩展名根本没有内置查看器——DICOM（.dcm、.ima）只能通过 DICOM 插件使用。若在没有相应能力的情况下打开，会抛出：

LicenseException: This document type requires the 'Dicom' plugin license.

没有任何查看器声明支持的扩展名会引发 FormatNotSupportedException。

解析完成后，配置确定：如果你传入了显式的配置对象则使用它，否则使用目录中该格式的默认配置。DocOptions.Password 会被复制到配置中，以便处理受保护的文档。

阶段 1b — 重定向模式（DefaultRender = false）

大多数每种格式的配置都会暴露一个 DefaultRender 标志。它在两条根本不同的路径之间进行选择：

• DefaultRender = true — 文档直接原生渲染为页面图像。
• DefaultRender = false — 文档首先 在内存中转换为 PDF，随后释放源引擎，由 PDF 查看器接管。生成的 PDF 包含真实文本，因此全文搜索能够得到精确的原生高亮；管线会为重定向的 PDF 打开 AllowSearch 和 AllowCopy，因为转换对用户是透明的。

默认情况下，XPS 和 MHT 使用重定向路径。对 HTML、Microsoft Project 等格式进行 PDF 投影可以实现原生搜索。如果生成的 PDF 只包含没有文本层的图像，则这些像素无法被搜索。

当你需要可搜索、带文本的投影时，请使用重定向模式——代价是文档打开时需要一次前置转换。

阶段 2 — 页面图像管线

每一次对 DocImage.axd 的页面请求都会执行固定的顺序：

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• 水印 — 根据许可证状态（无许可证、已过期的临时或订阅许可证、无效域名、超出许可证版本的构建）以及 DocOptions.Watermark 中的自定义文字应用。拥有许可证但未设置自定义水印的站点会跳过此步骤。
• 旋转/翻转 — 用户在小部件中设置的每页状态（90°/180°/270°、水平和垂直翻转）会存入会话，并在该页后续的每次渲染时应用。
• 缩放 — 通过将渲染后的页面按请求的尺寸进行缩放，生成缩略图和不同的缩放级别。
• 注释烧录 — 已保存的注释会绘制到位图上，从而在导出和页面图像中显示这些注释。
• 编码 — 最终结果以 PNG 编码并直接写入响应。

处理程序内部的错误会以 PNG 错误图像（白底红字）形式返回，状态码为 200，而不是 HTTP 错误页面，这样小部件可以在页面区域直接显示它们。

页面缓存

BaseConfig.CachePages（默认 true）会在文档会话的整个生命周期内将渲染好的页面图像保存在内存中，因此再次访问同一页面时不会重新渲染。BaseConfig.ImageResolution（25–300 DPI，0 表示使用格式的默认值）是主要的质量和内存调节参数；每种格式的默认值列在 格式配置 中。

在单节点环境下，会话和缓存页面存放在工作进程的内存中。应用池回收——无论是计划的、因编辑 Web.config 而触发的，还是因空闲超时导致的——都会丢失所有打开的文档会话，随后小部件会显示 Document session not found. Please re-open document.。在分布式模式下（参见会话与安全），会话会从共享存储中重新构建。

调优指南