许可证设置
Doconut 在何处查找您的许可证文件
即使没有许可证,Doconut 仍然可以渲染文档——每页仅带有评估水印。本页介绍提供许可证的四种方式,以及在设置多个时的确切优先级。
提供许可证的四种方式
共有四种:DoconutOptions 上的三种显式来源——流、原始内容或文件路径——以及在未设置任何来源时的自动发现。当设置多个时,优先级如下:
LicenseStream 优先于 LicenseContent 优先于 LicensePath 优先于 自动搜索。
按路径
LicensePath 会原样传递给 File.Exists。相对路径相对于进程的 当前工作目录 解析——而不是您的项目文件夹,也不是 Program.cs 所在的文件夹。如果路径无法解析,Doconut 不会抛出异常,也 不会 回退到自动搜索——它仅仅不加载许可证,查看器会显示水印。只有在 LicensePath、LicenseContent 或 LicenseStream 均未设置时,才会运行自动搜索。位于同一文件夹的每个插件许可证文件(Doconut.Viewer.<Capability>.lic)会随之读取,因此当插件许可证与基础许可证并列时,LicensePath 和 AddPlugin<...>() 能协同工作。
建议使用绝对路径(例如由 IWebHostEnvironment.WebRootPath 或 AppContext.BaseDirectory 构建),或者完全跳过 LicensePath,依赖下面的自动发现。
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});按流
LicenseStream 在启动时读取一次——当许可证来自机密存储而非磁盘文件时非常有用。
// 优先级: LicenseStream > LicenseContent > LicensePath > 自动搜索。
builder.Services.AddDoconut(options =>
{
options.LicenseStream = licenseStream;
});按内容
LicenseContent 接受许可证文本本身——可以来自环境变量、数据库或机密管理器:
// License XML 来自数据库、环境变量或密钥管理器 —
// 磁盘上没有文件。仅在 LicenseStream 时才会被覆盖。
builder.Services.AddDoconut(options =>
{
options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});自动发现
如果未配置这三种显式来源,Doconut 将自行搜索许可证:
// 无需配置,Doconut 会自行搜索许可证,仅在以下两个文件夹中:
// 1. {CurrentDirectory}/wwwroot
// 2. {AppContext.BaseDirectory}/wwwroot (构建输出文件夹中的 wwwroot)
// 它首先查找 Doconut.lic;如果不存在,则查找 Doconut.Viewer.lic 以及任何
// 每个插件的 Doconut.Viewer.<Capability>.lic 文件。
builder.Services.AddDoconut();按顺序探测的文件夹以及查找的文件名如下:
1. {CurrentDirectory}/wwwroot
2. {AppContext.BaseDirectory}/wwwroot
Filenames, in order (each one looked for in folder 1, then folder 2):
Doconut.lic — legacy all-in-one license; if found, nothing else is read
Doconut.Viewer.lic — base viewer license
Doconut.Viewer.<Capability>.lic — per-plugin licenses, read only when Doconut.Viewer.lic was found不会读取位于 wwwroot 文件夹之外的任何内容:输出文件夹本身或 wwwroot/lib 中的 .lic 将被忽略。
将许可证复制到输出文件夹
当进程未从项目文件夹运行——例如已发布的应用、IIS、容器或测试运行器——第一次探测会失效,第二次探测({AppContext.BaseDirectory}/wwwroot)必须找到文件。此 MSBuild 目标在每次构建时将许可证复制到该位置:
<Target Name="CopyLicensesToOutput" AfterTargets="Build">
<ItemGroup>
<DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
<StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
</ItemGroup>
<!-- 先删除,这样在 wwwroot 中重命名或删除 .lic 也会从输出中移除。 -->
<Delete Files="@(StaleOutputLicenses)" />
<Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>目标必须是 $(OutDir)wwwroot:复制到输出根目录的 .lic 永远不会被自动搜索到。本页的 LicensePath 示例指向同一位置。
将
.lic文件排除在源代码控制之外——将它们与应用一起部署,或通过LicenseContent或LicenseStream从机密存储注入许可证。
没有许可证会怎样
缺少许可证不会抛出异常。AddDoconut() 成功,应用启动,查看器运行——但每页都带有评估水印,且没有授予任何可选功能。
找到但被拒绝的许可证文件情况不同。无效签名、篡改、列入黑名单,或构建版本超出许可证的版本窗口,会导致 OpenDocumentAsync 抛出 LicenseException,并伴随 License.RejectionMessage。已过期的临时许可证仍以水印模式继续。订阅日期已过的付费许可证仍然可用,保持清洁并具备其功能,适用于该日期之前发布的所有构建。
插件需要功能
为没有相应授权的插件注册是不同的:对于缺少许可证、旧版 TRIAL 文件,或不具备该功能的付费许可证,AddDoconut() 会抛出 InvalidOperationException,导致应用无法启动。例如,注册 Converter 插件而没有授予 Converter 的许可证:
InvalidOperationException: The Converter plugin is registered via AddPlugin but no active
license grants Converter. Remove the AddPlugin<...>() call or install a license (or
trial/demo) that includes Converter.该信息直接告诉您解决办法:要么删除该插件的 options.AddPlugin<...>() 调用,要么安装付费许可证或授予该功能的有效临时/演示(NFR)许可证。临时注册允许在其到期后仍然存活,以便已配置的应用在运行时降级而不是在重启时崩溃;一旦过期,其功能仍会被撤销。
验证已加载的许可证
使用 IDoconutLicenseService,这是 SDK 使用的相同权威来源,用于公开经过身份验证的诊断端点或驱动功能标记。不要返回许可证内容或密钥。
app.MapGet("/api/doconut/license", (IDoconutLicenseService license) => Results.Ok(new
{
viewer = license.IsViewerLicensed || license.IsTemporary,
temporary = license.IsTemporary,
search = license.IsCapabilityGranted(LicenseCapability.Search),
annotation = license.IsCapabilityGranted(LicenseCapability.Annotation),
converter = license.HasConverter,
dicom = license.HasDicom
}));许可证在 AddDoconut() 注册期间读取。ResetLicense 目前是一个兼容性属性,没有活动的重新加载路径,因此更换许可证文件需要重新启动应用程序。
故障排除矩阵
| 症状 | 可能原因 | 检查 |
|---|---|---|
| 查看器工作但每页都有水印 | 未加载许可证,或临时许可证已过期 | 解决 IDoconutLicenseService;验证输出目录和进程工作目录 |
AddDoconut() 对插件抛出异常 | 许可证未授予该插件功能 | 检查 IsCapabilityGranted(...) 并移除未购买的注册 |
| 配置的相对路径在本地可用但在 IIS/容器中不可用 | 进程工作目录已更改 | 使用 AppContext.BaseDirectory 或绝对路径 |
替换的 .lic 文件无效 | 单例许可证服务已创建 | 重新启动应用程序 |
OpenDocumentAsync 抛出 LicenseException | 签名、域、版本窗口、黑名单或插件运行时门拒绝了许可证 | 读取异常/拒绝信息,但不要向不受信任的客户端暴露 |
后续步骤
此页面对您有帮助吗?