查看器 – Doconut 文档

Viewer（命名空间 Doconut）是用于从 Razor 页面、MVC 控制器、Blazor 组件或最小 API 打开文档的公共入口点。它是 sealed，通过 AddDoconut() 注册为 transient 服务，并通过构造函数注入解析——绝不要直接实例化它。

之前的 .NET Standard 库公开了一个接受内存缓存、HTTP 上下文访问器以及一个或多个许可证路径的公共构造函数。该构造函数已被移除；服务图提供这些依赖项。

Viewer 不持有每个请求的状态，并且有意不实现 IDisposable：文档会话独立存储在会话缓存中，因此释放服务永远无法关闭已打开的文档（参见 Core Concepts → How the Viewer Works）。

OpenDocumentAsync

打开文档并返回客户端小部件用于所有后续请求的会话令牌。每次打开都是异步的——没有同步的 OpenDocument。

重载	使用场景
`Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)`	从磁盘打开，自动检测格式并使用该格式的默认配置
`Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)`	需要针对每种格式的渲染选项（`PdfConfig`、`WordConfig`，…）
`Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)`	文档不是磁盘上的文件（上传、数据库、Blob）。`fileInfo` 必须包含正确的扩展名——它用于格式检测

csharp

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

需要处理的异常：

LicenseException — 找到的许可证被拒绝（消息包含拒绝原因），或者该格式需要的插件功能不再被授予。日历到期且没有拒绝信息时，会降级为带水印的渲染而不是抛异常。
FormatNotSupportedException — 不支持的文档格式 ''。
InvalidDataException — 文件内容损坏或与其扩展名不匹配。

CloseDocument

text

void CloseDocument(string token)

从缓存中移除会话（立即释放文档引擎），删除安全标记，并撤销访问授权。可选——滑动过期会执行相同的清理——但建议对大文档使用。

GetPageCount

text

int GetPageCount(string token)

打开会话的总页数。如果令牌未知或已过期则抛出异常。

能力标志

成员	含义
`bool IsSearchEnabled`	当前许可证授予 `Search` 权限
`bool IsAnnotationEnabled`	当前许可证授予 `Annotation` 权限

在 Razor 视图中使用这些属性，仅在服务器实际提供时渲染带许可证的功能区——参见快速入门。

DocOptions

每次打开的、与格式无关的选项（命名空间 Doconut）：

类型	属性	默认值	描述
`string`	`Password`	`""`	受保护文档的密码（自动复制到格式配置中）。
`int`	`ImageResolution`	`0`	已废弃。仅为兼容性保留——请在格式配置上设置 `ImageResolution`。
`string`	`Watermark`	`""`	在渲染页面上绘制的自定义水印文本。格式字符串：`"^Text~Color~FontSize~FontName~Opacity~Angle"`，例如 `"^Sample Copy~Red~24~Verdana~80~-45"`。
`int`	`TimeOut`	`60`	会话的滑动过期时间（分钟）。
`bool`	`IsSecured`	`true`	当前未强制执行 — 保留。令牌绑定由全局的 `DoconutOptions.UnsafeMode` 控制（参见 Core Concepts → Sessions & Security）。

该类还公开了有意超出普通单主机查看流程的专用属性：

类型	属性	默认值	描述
`bool`	`IsWebFarm`	`false`	标记打开操作为共享存储场景。注意大小写——之前的库写作 `IsWebfarm`。
`string`	`WebFarmPath`	`""`	该工作流使用的共享路径。之前写作 `WebfarmPath`。在普通单主机查看器中为空，在分布式部署描述的发布路径中也不需要。
`bool`	`EditMode`	`false`	保留用于单独分发的编辑工作流；标准查看器请保持 `false`。

自定义水印

DocOptions.Watermark 使用六个由波浪号分隔的字段。可选的前导 ^ 用于请求全角布局：

text

^Text~Color~FontSize~FontName~Opacity~Angle

csharp

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

字段	示例	含义
前导 `^`	`^`	可选的全角布局。如果没有此符号，则使用普通水印放置方式。
文本	`Confidential`	在每页上渲染的文本。不能为空。
颜色	`Red`	绘图层能够识别的命名颜色。
字体大小	`24`	字体大小；无效的数值输入将回退到渲染器默认值。
字体名称	`Verdana`	请求的字体族。请确保在部署环境中已安装该字体。
不透明度	`80`	0 到 255 的字节值。必须能够成功解析。
角度	`-45`	以度为单位的旋转角度；无效的数值输入将回退到默认值。

解析器期望在可选的 ^ 之后恰好有六个字段。无效的定义会被 SDK 可见的 Invalid Watermark 回退替代，而不是静默消失。

许可证决策

许可证状态	提供的自定义值	渲染结果
有效的付费查看器许可证	否	干净页面
有效的付费查看器许可证	是	自定义水印
活跃的临时/演示基础查看器	否	干净的基础查看器页面
活跃的临时/演示基础查看器	是	当适用干净的基础查看器路径时的自定义水印
缺失、被拒绝、已过期、版本错误或域名无效的许可证	任意	强制/评估水印；自定义值不会覆盖它
插件渲染在评估规则下	任意	评估水印

相同的决策同样适用于提供的页面图像和批注导出。动画 GIF 输出会逐帧加盖水印。因此，自定义水印是经许可的应用功能，而不是用来替换或抑制评估水印的手段。

批注 API

服务器端批注加载和导出。完整的操作指南位于 Guides → Annotations；概览如下：

成员	用途
`AnnotationManager GetAnnotationManager(string token)`	绑定到打开会话页面尺寸的管理器
`AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)`	具有显式页面尺寸的管理器
`AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)`	独立于会话的管理器
`void LoadAnnotationData(string token, AnnotationManager manager)`	将 C# 构建的批注加载到会话中
`void LoadAnnotationData(string token, string annotationData)`	从 `AnnotationManager.GetAnnotationData()` 返回的已编码页面/Base64 包中加载批注
`void LoadAnnotationXML(string token, XmlDocument annotationXml)`	从 XML 加载批注
`XmlDocument GetAnnotationXML(string token)`	将会话的批注导出为 XML
`Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)`	带有嵌入批注的 PDF
`Task<int> ExportAnnotationsToPngAsync(…)`	带有嵌入批注的 PNG 文件
`Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)`	每页 PNG 带批注的 ZIP 包

这些方法均需要会话令牌。之前库中无会话的 GetAnnotationManager(pageWidth, pageHeight) 形式仍可用于在会话外构建批注，但加载时仍需令牌。

DICOM 元数据

text

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

该方法用于 API 对齐，但此包无法提供技术性的 DICOM 标签：元数据读取器仅随 .NET 8 构建提供。它在 DICOM 和非 DICOM 会话中返回 null；在 DICOM 会话中还会写入一次性警告，说明平台限制。页面、帧和动画渲染仍受支持。

资源助手 — ReferenceCss / ReferenceScripts

为 UseDoconutResources() 提供的嵌入式资源生成 <link> / <script> 标签，按正确的依赖顺序输出。对许可证限制的功能（如搜索和注释）的资源包仅在许可证启用相应功能时才会生成，确保客户端 UI 与服务器行为保持一致。

text

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig 标志: IncludeBootstrapCss、IncludeViewerCss、IncludeSearchCss（搜索受限）、IncludeAnnotationCss（注释受限）。

ScriptConfig 标志: IncludeJQuery（所有其他标志的必需项）、IncludeBootstrap、IncludeViewerScripts（核心：docViewer.js + splitter + links）、IncludeSearchScripts 与 IncludeSearchBar（搜索受限）、IncludeAnnotationScripts 与 IncludeAnnotationBar（注释受限）。

html

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

这些助手是提供浏览器资源的推荐方式。将 docViewer.js、documentLinks.js 和 docViewer.UI.js 复制到 wwwroot 的应用程序应在页面通过生成的标签渲染后删除这些复制的文件。