查看器

Viewer（namespace Doconut）是用于从 MVC 控制器、Web Forms 页面和处理程序打开文档的公共入口点。它是由 DoconutHost.Initialize 组合的 瞬态 服务；在使用的地方解析它：

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() 也可以在 DoconutHost.Initialize 运行后使用——它解析相同的服务——这使得从经典包迁移的代码仍能编译。在 Initialize 之前，它会抛出 InvalidOperationException。

Viewer 不持有每个请求的文档状态，并且有意 不 实现 IDisposable：文档会话独立于它存在，因此释放 Viewer 永远不会关闭已打开的文档（参见 查看器工作原理）。

OpenDocumentAsync

打开文档并返回小部件在后续每个请求中使用的会话令牌。当 UnsafeMode 为 false（默认值）时，令牌会授予当前请求的 ASP.NET 会话——请在具有会话状态的请求中调用它（参见 会话与安全）。

// 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 (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

需要处理的异常：

• LicenseException — 找到了许可证但被拒绝（消息中包含原因），或格式需要许可证未授予的插件功能。
• FormatNotSupportedException — 没有查看器能够处理该文件的扩展名。
• InvalidDataException — 内容损坏或与其扩展名不匹配。

OpenDocument（同步）

用于 Web Forms 代码隐藏以及其他不使用异步页面的代码：

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

每个方法都会返回令牌并将其存储在 viewer.Token 中。fileName 必须带有正确的扩展名。这些包装器可以安全地从 Web Forms 页面调用：打开路径永远不会在 ASP.NET 请求上下文中恢复，因此等待它不会导致死锁。并非所有异步 Doconut API 都是 如此——请参见 转换插件 的 Web Forms 部分。

关闭文档

void CloseDocument(string token)

移除会话（立即释放文档引擎），从当前请求的 ASP.NET 会话中删除该 token 的授权，并撤销 token。可选——滑动过期会执行相同的清理——但建议在处理大文档时使用。

会话查询

如果 token 未知或已过期，则会抛出异常。

DocOptions（文档选项）

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

自定义水印

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

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

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

解析器在可选 ^ 之后恰好期望六个字段。无效的定义会被替换为可见的 Invalid Watermark 文本，而不是悄然消失。

许可证决策

相同的决策适用于提供的页面以及注释导出。自定义水印是已授权应用的功能，而不是替换评估水印的手段。

注释 API

服务器端注释加载与导出。完整演练请参见注释。

DICOM 元数据

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

在此包中它始终返回 null，并且小部件的元数据请求返回 501 Not Implemented：在 .NET Framework 上无法读取 DICOM 标签。DICOM 渲染 — 页面、帧和动画 — 可以工作。参见 DICOM 插件。

资源助手 — ReferenceCss / ReferenceScripts

为资源模块在 DoconutOptions.ResourcesPath 下提供的资源（按依赖顺序）输出 <link> 和 <script> 标签。受许可证限制的功能（搜索、注释）的文件仅在许可证授予时才会输出。

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // license state, for guarding ribbon init code
bool IsAnnotationEnabled { get; }

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

ScriptConfig 标志: IncludeJQuery（所有其他脚本均依赖）、IncludeBootstrap、IncludeViewerScripts（核心查看器脚本）、IncludeSearchScripts 与 IncludeSearchBar（受搜索许可限制）、IncludeAnnotationScripts 与 IncludeAnnotationBar（受注释许可限制）。

两者均返回 HTML：在 MVC 5 中使用 @Html.Raw(...) 编写它们（在控制器中生成——视图没有 @inject），或在 Web Forms 中使用 <%= %>。快速入门 展示了两种写法。

RenderViewer

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

返回一个 <script> 块，用于在 id 为 elementId 的元素上初始化小部件并显示文档：docViewer({...}) 根据 ViewerConfig 构建（默认：BasePath: '/'、ResPath: 'doconut-res/images'），随后调用 .View(token)。在查看器脚本之后写入它。生成的脚本不保留对查看器对象的引用，因此如果页面有自己的工具栏，应手动初始化小部件。参见 ViewerConfig。

Web 农场

string? AccessToken 保存分布式模式激活且 UnsafeMode 为 false 时最近一次打开所签发的票据；在单服务器情况下为 null。将其与 token 一起发送给小部件：objViewer.View(token, access)。