安装

将 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。

安装包

bash
dotnet add package Doconut.NETStandard

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

bash
dotnet add package Doconut.NETStandard --version 26.10.0

Doconut.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 会话状态验证每个页面请求。

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());

命名空间

配置类型不再分布在四个命名空间中。在此版本中,几乎所有内容都位于根 Doconut 命名空间下:

csharp
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 接受以下可设置属性。每个属性都是可选的——当属性未设置时,将使用下面的默认值。

属性默认值描述
ShowDoconutInfofalse当 true 时,未带 token 的请求会返回版本横幅而不是 404。可用于快速检查;在生产环境中请关闭。
UnsafeModefalse当 true 时,跳过页面请求的 ASP.NET 会话安全检查。生产环境请关闭。注意拼写——之前的库将其称为 UnSafeMode。
MiddlewarePath"/doconut"页面-图像端点的协调值。它会被验证,但本身不会挂载分支;请保持与实际的 UseDoconut() 映射以及客户端 BasePath 对齐。
ResourcesPath"/doconut-res"嵌入的 JS/CSS/图片资源的提供位置。
LicensePath"" (empty string)许可证文件的路径。空字符串表示继续查找下一个来源,然后自动搜索。
LicenseContent"" (empty string)原始许可证内容——来自环境变量、密钥管理器或数据库。
LicenseStreamnull许可证作为流,在启动时读取一次。
ResetLicensefalse保留的兼容性标志。许可证在 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 的 JS/CSS/图片提供位置
    options.UnsafeMode      = false;          // 保持会话安全开启
    options.ShowDoconutInfo = false;
});

后续步骤

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

此页面对您有帮助吗?