许可证设置

Doconut 查找许可证文件的位置

即使没有许可证，Doconut 仍然可以渲染文档——每页仅会带有评估水印。本页介绍提供许可证的四种方式，以及当设置多个时的精确优先级。

提供许可证的四种方式

共有四种：DoconutOptions 上的三种显式来源——流、原始内容或文件路径——以及当它们均未设置时的自动发现。当设置多个时，优先级如下：

LicenseStream 优先于 LicenseContent 优先于 LicensePath 优先于 自动搜索。

通过路径

LicensePath 会原样传递给 File.Exists。相对路径会相对于进程的 当前工作目录 解析——而不是你的项目文件夹，也不是 Program.cs 所在的文件夹。如果路径无法解析，Doconut 不会抛异常，也 不会 回退到自动搜索——它仅仅不加载许可证，查看器会显示水印。只有在 LicensePath、LicenseContent 和 LicenseStream 均未设置时，自动搜索才会运行。

建议使用绝对路径（例如由 IWebHostEnvironment.WebRootPath 或 AppContext.BaseDirectory 构建），或者完全省略 LicensePath，改用下面的自动发现方式。

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "Doconut.Viewer.lic");
});

通过流

LicenseStream 在启动时读取一次——当许可证来自密钥存储而不是磁盘文件时非常有用。

csharp
// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

通过内容

LicenseContent 接受许可证文本本身——可以来自环境变量、数据库或密钥管理器：

csharp
// License XML from a database, environment variable, or secret manager —
// no file on disk. Beaten only by LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

自动发现

不配置上述三种显式来源，Doconut 会自行搜索许可证：

csharp
// Configure nothing, and Doconut searches for the license itself:
//   1. {CurrentDirectory}/wwwroot
//   2. {CurrentDirectory}/wwwroot/lib
//   3. AppContext.BaseDirectory  (the build output folder)
// It looks for Doconut.Viewer.lic plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
builder.Services.AddDoconut();

探测目录的顺序以及每个目录中查找的文件名如下：

text
1. {CurrentDirectory}/wwwroot
2. {CurrentDirectory}/wwwroot/lib
3. AppContext.BaseDirectory

Filenames (checked in each directory above, in order):
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-plugin license, alongside Doconut.Viewer.lic

将许可证复制到输出文件夹

LicensePath 与自动搜索的 AppContext.BaseDirectory 探测，都需要 .lic 文件与生成的应用程序位于同一目录——而不仅仅在源码的 wwwroot 中。SDK 自带的测试应用会在每次构建时通过以下 MSBuild 目标复制它：

xml
<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
  </ItemGroup>
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)" SkipUnchangedFiles="true" />
</Target>

将 .lic 文件排除在源码控制之外——将其与应用程序一起部署，或通过 LicenseContent 或 LicenseStream 从密钥存储注入许可证。

没有许可证会怎样

缺失许可证不会抛异常。AddDoconut() 成功，应用启动，查看器运行——但每页都会带有评估水印，且不会授予任何可选功能。

如果找到了许可证文件但被拒绝，则情况不同。签名无效、被篡改、被列入黑名单，或构建时间超出许可证的版本窗口，都会导致 OpenDocumentAsync 抛出 LicenseException，并附带 License.RejectionMessage。日历已过期且没有拒绝信息的许可证会继续以水印模式运行。

插件需要功能

为未拥有相应授权的插件注册会产生不同的结果：对于缺失的许可证、旧的 TRIAL 文件，或不包含该功能的付费许可证，AddDoconut() 会抛出 InvalidOperationException，导致应用无法启动。例如，注册 Converter 插件但没有授予 Converter 的许可证：

text
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 使用的同一真实数据源）来公开经过身份验证的诊断端点或驱动功能标记。不要返回许可证内容或密钥。

csharp
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签名、域、版本窗口、黑名单或插件运行时门禁拒绝了许可证读取异常/拒绝信息，但不要向不受信任的客户端暴露

后续步骤

  • 授权 — 功能、许可证层级以及在运行时验证实际加载的内容。
  • 故障排查 — 水印、被拒绝的许可证和功能错误。

此页面有帮助吗？