安装

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

.NET 6 的基础 Doconut 查看器以一个 NuGet 包的形式提供,可插入任何 ASP.NET Core 应用程序。可选插件使用独立的包。本页安装基础包并注册中间件——在首次渲染之前所需的最小配置。

要求

该包在以下平台上运行:

平台支持
Windows x64 / x86是
Linux x64, glibc-based (Debian, Ubuntu, the official mcr.microsoft.com/dotnet/aspnet:6.0-bookworm-slim image)是
Alpine and other musl-based distributions否
macOS否

在 Linux 上,在打开第一个文档之前请安装字体配置库:

bash
apt-get update && apt-get install -y libfontconfig1

在 RHEL、Fedora 及类似发行版上,该包为 fontconfig(dnf install -y fontconfig)。这是 Doconut 唯一需要的系统包:它使用的本机库已随 NuGet 包一起提供,libgdiplus 并非必需。
在 Docker 中,建议使用 aspnet:6.0-bookworm-slim(Debian 12):默认的 aspnet:6.0 标签是 Debian 11,其软件源可能导致 libfontconfig1 安装失败。页面使用服务器上已安装的字体进行渲染,因此请参阅故障排除了解字体和 Linux 错误信息。

安装包

bash
dotnet add package Doconut.NET6

未指定版本的命令会安装最新的稳定版。若要固定本文档所描述的版本,请将版本号作为单独的选项传入:

bash
dotnet add package Doconut.NET6 --version 26.10.0

Doconut.NET6 是包的标识符。版本后缀属于下载的 Doconut.NET6.<version>.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。UseDoconut() 会响应所有到达它的请求,因此请使用 app.Map 将其挂载在单独的分支上。会话注入也是必需的——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.Map("/doconut", branch => branch.UseDoconut());

所有选项

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

属性默认值描述
ShowDoconutInfofalse当 true 时,未携带 token 的请求会返回版本横幅而不是 404。可用于快速检查;在生产环境中请关闭。
UnsafeModefalse当 true 时,跳过页面请求的 ASP.NET 会话安全检查。请在生产环境中关闭。
MiddlewarePath"/doconut"页面-图像端点的协调值。该值会被验证,但本身不会挂载分支;请保持其与实际的 UseDoconut() 映射以及客户端 BasePath 对齐。
ResourcesPath"/doconut-res"嵌入的 JS/CSS/图片资源的提供位置。
LicensePath"" (empty string)许可证文件的路径。为空表示会继续查找下一个来源,然后自动搜索。
LicenseContent"" (empty string)原始许可证内容——来自环境变量、密钥管理器或数据库。
LicenseStreamnull许可证作为流,在启动时读取一次。
ResetLicensefalse保留的兼容性标志。当前 .NET 6 服务在 AddDoconut() 时读取许可证;更换许可证后请重启应用。
MaxConcurrentEditorSessions200实时编辑器会话的最大数量(使用 DocOptions.EditMode 打开的文档)。超过此数后,最久未使用的空闲编辑器会话将被关闭。普通查看器会话不计入。0 或负值表示无限制。
EditorSnapshotEveryOps50在启用编辑器持久化 (AddDoconutEditorPersistence) 时,每 N 次记录的更改对实时文档进行快照。0 或负值表示在会话期间永不快照。持久化关闭时此设置无效。

当设置了多个来源时,许可证的优先级顺序为: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 查找许可证文件的位置。

此页面对您有帮助吗?