安装
将 Doconut 添加到您的 .NET Standard 2.1 项目
该库的基础 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 使用 |
该包仅在 Windows 上运行。对于 Linux 主机,请使用 Doconut.NET8 或 Doconut.NET6。
如果应用程序运行在 .NET Framework 上,这不是合适的包。请改用 Doconut.NETFramework;从 26.9.0 起,它需要 .NET Framework 4.7.2。
安装包
dotnet add package Doconut.NETStandard未指定版本的命令会安装最新的稳定版。若要锁定本文档所描述的版本,请将版本号作为单独的选项传入:
dotnet add package Doconut.NETStandard --version 26.10.0Doconut.NETStandard 是包的标识符。版本后缀属于下载的 Doconut.NETStandard.<version>.nupkg 文件名,并不是标识符的一部分。
版本号代表代数
这比包名更为重要。两个 .NET Standard 代的库使用相同的包标识符发布,只有版本号能够区分它们:
| 版本 | 目标 | 接口 |
|---|---|---|
| 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。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());命名空间
配置类型不再分布在四个命名空间中。在此版本中,几乎所有内容都位于根 Doconut 命名空间下:
using Doconut; // Viewer、DoconutOptions、DocOptions,全部格式配置
using Doconut.Middleware; // AddDoconut、UseDoconut、UseDoconutResources
using Doconut.Clouds; // 云端和文件共享配置
using Doconut.Configs.Conversion; // ConversionTarget类型名称本身没有变化——PdfConfig、WordConfig、ExcelConfig、CssConfig、ScriptConfig 以及其余的仍然存在。如果您正在迁移现有应用程序,大多数文件只需删除两行 using;请参阅迁移指南。
所有选项
DoconutOptions 接受以下可设置属性。每个属性都是可选的——当属性未设置时,将使用下面的默认值。
| 属性 | 默认值 | 描述 |
|---|---|---|
ShowDoconutInfo | false | 当 true 时,未带 token 的请求会返回版本横幅而不是 404。可用于快速检查;在生产环境中请关闭。 |
UnsafeMode | false | 当 true 时,跳过页面请求的 ASP.NET 会话安全检查。生产环境请关闭。注意拼写——之前的库将其称为 UnSafeMode。 |
MiddlewarePath | "/doconut" | 页面-图像端点的协调值。它会被验证,但本身不会挂载分支;请保持与实际的 UseDoconut() 映射以及客户端 BasePath 对齐。 |
ResourcesPath | "/doconut-res" | 嵌入的 JS/CSS/图片资源的提供位置。 |
LicensePath | "" (empty string) | 许可证文件的路径。空字符串表示继续查找下一个来源,然后自动搜索。 |
LicenseContent | "" (empty string) | 原始许可证内容——来自环境变量、密钥管理器或数据库。 |
LicenseStream | null | 许可证作为流,在启动时读取一次。 |
ResetLicense | false | 保留的兼容性标志。许可证在 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 的 JS/CSS/图片提供位置
options.UnsafeMode = false; // 保持会话安全开启
options.ShowDoconutInfo = false;
});后续步骤
此页面对您有帮助吗?