安装
将 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 上,在打开第一个文档之前,请安装字体配置库:
apt-get update && apt-get install -y libfontconfig1在 RHEL、Fedora 以及类似的发行版中,该包是 fontconfig(dnf install -y fontconfig)。这是 Doconut 唯一需要的系统包:它使用的本机库已随 NuGet 包一起提供,libgdiplus 并非必需。页面使用服务器上已安装的字体进行渲染,因此请参阅 故障排除 了解字体和 Linux 错误信息。
安装包
dotnet add package Doconut.NET8未指定版本的命令会安装最新的稳定版。若要锁定本文档所描述的版本,请将版本号作为单独的选项传入:
dotnet add package Doconut.NET8 --version 26.10.0Doconut.NET8 是包的标识符。版本后缀属于下载的 Doconut.NET8.<version>.nupkg 文件名,并不属于标识符的一部分。
注册 Doconut
AddDoconut() 是唯一的注册入口点——只有一个重载,它会将 Viewer 服务、许可证服务以及渲染基础设施注入到 DI 容器中。
两个中间件调用完成设置,并且它们的顺序很重要:UseDoconutResources() 必须在 UseDoconut() 之前运行。 UseDoconut() 是终止中间件,因此先调用它会导致对 /doconut-res 资源的所有请求都无法到达资源处理程序并返回 404。UseDoconut() 会响应所有到达它的请求,因此请使用 app.Map 将其挂载在单独的分支上。会话绑定也是必需的——Doconut 的默认文档安全会根据 ASP.NET 会话状态验证每个页面请求。
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 接受以下可设置的属性。每个属性都是可选的——当属性未设置时,下面的默认值将生效。
| 属性 | 默认值 | 描述 |
|---|---|---|
ShowDoconutInfo | false | 当 true 时,未包含 token 的请求会返回版本横幅而不是 404。可用作快速检查;在生产环境中请关闭。 |
UnsafeMode | false | 当 true 时,跳过页面请求的 ASP.NET 会话安全检查。请在生产环境中关闭。 |
MiddlewarePath | "/doconut" | 页面‑图片端点的协同值。该值会被验证,但本身不会挂载分支;请保持与实际的 UseDoconut() 映射以及客户端 BasePath 对齐。 |
ResourcesPath | "/doconut-res" | 嵌入的 JS/CSS/图片资源的提供位置。 |
LicensePath | "" (empty string) | 许可证文件的路径。为空表示会继续查找下一个来源,然后自动搜索。 |
LicenseContent | "" (empty string) | 原始许可证内容——来自环境变量、密钥管理器或数据库。 |
LicenseStream | null | 许可证作为流,在启动时读取一次。 |
ResetLicense | false | 保留的兼容性标志。当前的 .NET 8 服务在 AddDoconut() 时读取许可证;更换许可证后请重新启动应用。 |
MaxConcurrentEditorSessions | 200 | 实时编辑器会话的最大数量(使用 DocOptions.EditMode 打开的文档)。超过此数量后,最久未使用的空闲编辑器会话将被关闭。普通查看器会话不计入此限制。0 或负值表示无限制。 |
EditorSnapshotEveryOps | 50 | 在启用编辑器持久化(AddDoconutEditorPersistence)时,每 N 次记录的更改会对实时文档进行快照。0 或负值表示在会话期间永不快照。持久化关闭时此设置无效。 |
当设置了多个来源时,许可证的优先级顺序为:LicenseStream 优先于 LicenseContent,后者优先于 LicensePath,再优先于自动搜索——请参阅 许可证设置。
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;
});下一步
此页面对您有帮助吗?