基础的 Doconut 查看器针对 .NET Standard 以单个 NuGet 包的形式提供，可插入任何 ASP.NET Core 应用。可选插件使用独立的包。本页将安装基础包，确认您的主机能够使用它，并注册中间件——在首次渲染之前的最小需求。

首先检查主机框架

该库面向 netstandard2.1。相较于之前的 netstandard2.0 构建，它的契约更窄，这是首先需要验证的点：

主机	支持
.NET Core 3.0 或更高版本，包括 .NET 5/6/7/8	是
.NET Framework（任何版本）	否 — netstandard2.1 无法被 .NET Framework 使用

如果应用运行在 .NET Framework 上，则此包不适合。请改用 Doconut.NETFramework；自 26.9.0 起它要求 .NET Framework 4.7.2。本次发布随附的参考应用目标为 net8.0。

安装包

bash

dotnet add package Doconut.NETStandard

未指定版本的命令会安装最新的稳定版。若要精确复现当前的 26.8.0 发行版，请另加版本选项：

bash

dotnet add package Doconut.NETStandard --version 26.8.0

Doconut.NETStandard 是包的 ID。文件名中的 .26.8.0 后缀属于下载的 Doconut.NETStandard.26.8.0.nupkg，并非 ID 的一部分。

版本号代表代数

这在这里比包名更重要。两个代数的 .NET Standard 库使用相同的包 ID，只有版本号能区分它们：

版本	目标	API
26.7.0 及以下	netstandard2.0	先前的集成
26.8.0 及以上	netstandard2.1	本文档中描述的集成

没有兼容层，也没有并存的包。提升版本即升级，编译器会立即报告 API 差异。

不要仅凭包名选择文档：

new Viewer(_cache, _accessor, …), UnSafeMode, 同步 OpenDocument(...), viewer.InitCache(), UseDoconutWebFarm，以及手动复制的查看器脚本指向先前的集成；
AddDoconut(), UseDoconutResources(), 注入的 Viewer，以及 OpenDocumentAsync(...) 指向此处记录的当前集成。

已翻译的先前的设置手册仍可使用。请使用迁移指南切换代数；包更新不会自动转换启动代码、查看器生命周期或浏览器资源。

注册 Doconut

AddDoconut() 是唯一的注册入口点——只有一个重载，它会将 Viewer 服务、许可证服务以及渲染基础设施注入 DI 容器。

两次中间件调用完成设置，顺序很重要：UseDoconutResources() 必须在 UseDoconut() 之前运行。UseDoconut() 为终结中间件，若先调用则所有对 /doconut-res 资源的请求都无法到达资源处理程序并返回 404。会话绑定同样必需——Doconut 默认的文档安全会对每个页面请求进行 ASP.NET 会话状态校验。

csharp

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // 会话状态需要缓存（MVC/Razor Pages 已经添加了一个）
builder.Services.AddSession(); // Doconut 文档安全依赖于 ASP.NET 会话状态

app.UseSession();          // 在调用 UseDoconut() 之前先调用 UseSession()
app.UseDoconutResources(); // 必须在 UseDoconut() 之前注册
app.UseDoconut();

命名空间

本次发布中，配置类型不再分散在四个命名空间，几乎全部位于根 Doconut 命名空间：

csharp

using Doconut;                       // Viewer, DoconutOptions, DocOptions, all format configs
using Doconut.Middleware;            // AddDoconut, UseDoconut, UseDoconutResources
using Doconut.Clouds;                // cloud and file-share configs
using Doconut.Configs.Conversion;    // ConversionTarget

类型名称本身未变——PdfConfig、WordConfig、ExcelConfig、CssConfig、ScriptConfig 等仍然存在。若要迁移已有应用，大多数文件只需删除两行 using；详情请参阅迁移指南。

所有选项

DoconutOptions 接受以下可设置属性。每个属性都是可选的——未设置时使用下列默认值。

属性	默认	描述
`ShowDoconutInfo`	`false`	为 `true` 时，未携带 `token` 的请求返回版本横幅而非 404。可用于快速检查；生产环境请关闭。
`UnsafeMode`	`false`	为 `true` 时，跳过页面请求的 ASP.NET‑session 安全检查。生产环境请关闭。注意拼写——旧库称其为 `UnSafeMode`。
`MiddlewarePath`	`"/doconut"`	页面‑图片端点的协同值。会进行校验，但本身不会挂载分支；请保持与实际 `UseDoconut()` 映射及客户端 `BasePath` 一致。
`ResourcesPath`	`"/doconut-res"`	嵌入的 JS/CSS/图片资源的提供路径。
`LicensePath`	`""`（空字符串）	许可证文件路径。为空时会尝试下一个来源，然后自动搜索。
`LicenseContent`	`""`（空字符串）	原始许可证内容——可来自环境变量、密钥管理器或数据库。
`LicenseStream`	`null`	以流形式提供的许可证，启动时读取一次。
`ResetLicense`	`false`	保留的兼容性标志。许可证在 `AddDoconut()` 时读取；更换许可证后请重启应用。

当设置了多个来源时的许可证优先级：LicenseStream 优先于 LicenseContent，再优先于 LicensePath，最后是自动搜索——详见许可证设置。

csharp

builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // 与应用映射和客户端 BasePath 对齐
    options.ResourcesPath   = "/doconut-res"; // 观看器的 JS/CSS/图片资源的提供路径
    options.UnsafeMode      = false;          // 保持会话安全开启
    options.ShowDoconutInfo = false;
});

下一步

快速入门 — 打开您的第一份文档并在浏览器中渲染。
许可证设置 — Doconut 查找许可证文件的位置。