插件系统

Doconut 的核心保持精简；可选功能以 插件 形式提供——独立的 NuGet 包，贡献查看器或服务，并由您的许可证开启。本页解释注册模型、许可证门控在运行时的行为，以及如何插入您自己的查看器。

注册插件

每个插件包都会公开一个插件类。您只需在启动时注册一次：

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddPlugin<TPlugin>() 实例化插件并在 DoconutOptions 上的插件注册表中调用其 Register 回调。插件贡献的所有内容都标记为插件的 必需功能。AddDoconut() 会立即验证已注册的插件：缺少许可证、旧版 TRIAL 文件，或付费许可证缺少该功能都会导致启动时出现 InvalidOperationException。临时/演示注册在过期后仍保留，但其运行时功能会在过期日期后被撤销。

合同

插件实现了一个刻意简小的接口：

public interface IDoconutPlugin
{
    string Name { get; }                          // 例如 "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // 许可证入口
    void Register(IDoconutPluginBuilder builder); // 贡献查看器/服务
}

在 Register 中，构建器接受两种贡献类型：

• builder.RegisterViewer(".dcm", () => new DicomViewer()) — 用于文件扩展名的查看器，
• builder.RegisterService<TContract>(() => …) — 供管道其他部分查找的类型化服务。

功能与门控

功能是许可证的计量单位。Converter 和 Dicom 作为可选插件提供；Search 和 Annotation 是以相同方式受门控的内置特性。基础查看器 不是 功能——它是前置条件，在许可证服务上以 IsViewerLicensed 形式公开。

启动时的验证通常会阻止未授权的插件进入请求管道。查看器工厂还会应用两条防御性运行时规则，当授权在启动后发生变化时这些规则会生效：

• 插件覆盖内置查看器（插件声明了内置注册表也处理的扩展名）：如果已授权该功能，插件查看器优先；如果未授权，Doconut 会静默回退到内置查看器。用户仍能看到文档——只是没有插件功能。
• 仅插件格式（例如 .dcm —— DICOM 没有内置查看器）：如果未授权该功能，打开调用会直接失败：

LicenseException: This document type requires the 'Dicom' plugin license.

有效的临时许可证会授予所有功能（并提供干净、未加水印的基础查看）。这常常是上线时的意外来源：使用缺少某些功能的已购许可证注册相同插件会导致 AddDoconut() 在启动时失败。部署前请将 IsCapabilityGranted(...) 与您的计划进行比较。相反，如果根本没有许可证，则不会授予任何功能——缺少许可证并不等同于临时许可证。

相同的门控也会在客户端出现：Viewer.ReferenceScripts() 和 ReferenceCss() 会在许可证启用相应功能（搜索、批注等）时 仅 输出对应的脚本/样式包，从而使小部件的 UI 与服务器实际行为保持一致。

功能与插件映射

产品 UI 将 “插件” 作为宽泛的功能标签，但服务器注册方式不同：

注释和普通搜索不使用 AddPlugin<TPlugin>()；只有在许可证授予相应功能时才会输出它们的包。转换器和 DICOM 是本文件集已发布的可选 IDoconutPlugin 实现。

已批准的 .NET 6 构件在与核心包相同的版本中包含 Doconut.NET6.Converter 和 Doconut.NET6.Dicom。

已发布的插件包

每个插件在 插件 下都有专属页面，提供其配置和使用方法。

自定义查看器 — 您自己的格式处理器

您可以直接从 Program.cs 将查看器插入管道，而无需编写插件包：

builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // 实现 IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // 可选默认配置
});

自定义查看器优先于 所有 — 包括内置和插件 — 并且不受许可证门控（它们是您的代码）。如果未提供默认配置，工厂会回退到 ImageConfig。

要点

• 插件需显式注册，其 LicenseCapability 在 AddDoconut() 期间得到验证 — 缺失或不足的非临时授权会快速失败。
• 覆盖式插件会优雅降级；仅插件格式会因 LicenseException 而失败。
• 有效的临时许可证会解锁所有功能；正式版仅解锁您购买的功能。发布前请使用 IDoconutLicenseService 进行验证。