安装

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

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

要求

平台支持
Windows x64 / x86是
Linux x64,基于 glibc(Debian、Ubuntu、官方 mcr.microsoft.com/dotnet/aspnet:8.0 镜像)是
Alpine 及其他基于 musl 的发行版否
macOS否

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

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

在 RHEL、Fedora 以及类似的发行版中,该包是 fontconfig(dnf install -y fontconfig)。这是 Doconut 唯一需要的系统包:它使用的本机库已随 NuGet 包一起提供,libgdiplus 并非必需。页面使用服务器上已安装的字体进行渲染,因此请参阅 故障排除 了解字体和 Linux 错误信息。

安装包

bash
dotnet add package Doconut.NET8

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

bash
dotnet add package Doconut.NET8 --version 26.10.0

Doconut.NET8 是包的标识符。版本后缀属于下载的 Doconut.NET8.<version>.nupkg 文件名,并不属于标识符的一部分。

注册 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 8 服务在 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"; // viewer\u0027s JS/CSS/images 的提供来源
    options.UnsafeMode      = false;          // 保持会话安全开启
    options.ShowDoconutInfo = false;
});

下一步

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

此页面对您有帮助吗?