安装

将 Doconut 添加到您的 .NET 6 项目

基础的 Doconut 查看器针对 .NET 6 以单个 NuGet 包的形式提供，可插入任何 ASP.NET Core 应用程序。可选插件使用独立的包。本页将安装基础包并注册中间件——这是首次渲染前的最小需求。

安装包

bash
dotnet add package Doconut.NET6

未指定版本的命令会安装最新的稳定版。若要精确复现当前的 26.7.0 版本，请将版本号作为单独的选项传入：

bash
dotnet add package Doconut.NET6 --version 26.7.0

Doconut.NET6 是包的标识。.26.7.0 后缀属于下载的 Doconut.NET6.26.7.0.nupkg 文件名，并不属于标识本身。

在升级前识别集成方式

Doconut.NET6 包标识曾被经典集成和当前的 .NET 6 集成共用。仅凭包名不要判断文档来源：

  • DocImage.axd、new Viewer(_cache, _accessor, ...)、同步的 OpenDocument(...) 以及手动复制的查看器脚本标识了经典集成；
  • 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.AddSession(); // Doconut document security rides on ASP.NET session state

app.UseSession();          // call UseSession() before UseDoconut()
app.UseDoconutResources(); // must be registered before UseDoconut()
app.UseDoconut();

所有选项

DoconutOptions 接受以下可设置属性。每个属性都是可选的——当属性未设置时，下面的默认值将生效。

属性默认值描述
ShowDoconutInfofalse当设为 true 时，未携带 token 的请求会返回版本横幅而不是 404。可用于快速检查；生产环境请关闭。
UnsafeModefalse当设为 true 时，页面请求将跳过 ASP.NET‑session 安全检查。生产环境请关闭。
MiddlewarePath"/doconut"页面‑图片端点的协同路径。该路径会被验证，但本身不会挂载分支；请保持与实际的 UseDoconut() 映射以及客户端 BasePath 对齐。
ResourcesPath"/doconut-res"嵌入的 JS/CSS/图片资源的提供路径。
LicensePath"" (空字符串)许可证文件的路径。为空表示会继续查找下一个来源，然后自动搜索。
LicenseContent"" (空字符串)原始许可证内容——可来自环境变量、密钥管理器或数据库。
LicenseStreamnull以流形式提供的许可证，仅在启动时读取一次。
ResetLicensefalse保留的兼容性标志。当前的 .NET 6 服务在 AddDoconut() 时读取许可证；更换许可证后请重启应用。

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

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // coordinate with app mapping and client BasePath
    options.ResourcesPath   = "/doconut-res"; // where the viewer's JS/CSS/images are served from
    options.UnsafeMode      = false;          // keep session security on
    options.ShowDoconutInfo = false;
});

后续步骤

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

此页面有帮助吗？