插件系统

使用插件扩展查看器

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

注册插件

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

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

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

合约

插件实现一个刻意保持简洁的接口：

text
public interface IDoconutPlugin
{
    string Name { get; }                          // e.g. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // the license gate
    void Register(IDoconutPluginBuilder builder); // contribute viewers/services
}

在 Register 方法中，构建器接受两种贡献方式：

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

能力与限制

能力即许可证单元。Converter 和 Dicom 作为可选插件提供；Search 和 Annotation 是内置功能，受同样的限制。基础查看器 不是 能力——它是前置条件，以 IsViewerLicensed 暴露在许可证服务上。

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

  • 插件覆盖内置查看器（插件声明了一个内置注册表也处理的扩展名）：如果拥有相应能力，插件查看器优先；如果没有，Doconut 会静默回退到内置查看器。用户仍然可以看到文档——只是没有插件功能。
  • 仅插件支持的格式（例如 .dcm —— DICOM 没有内置查看器）：如果缺少相应能力，打开调用会直接失败：
text
LicenseException: This document type requires the 'Dicom' plugin license.

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

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

功能与插件映射

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

功能启用方式能力贡献
注释内置于查看器；包含注释资源Annotation浏览器编辑、会话持久化以及嵌入式导出
搜索内置于可搜索格式的查看器；包含搜索资源并在需要时启用提取Search原生文本索引、突出显示和结果导航
转换器安装 Doconut.NET8.Converter 并注册 ConverterPluginConverterC# 转换服务和可选的网页小部件
DICOM安装 Doconut.NET8.Dicom 并注册 DicomPluginDicom医学图像查看（.dcm 和 .ima — 仅插件格式）

已发布的插件包

插件包能力贡献
转换器Doconut.NET8.ConverterConverter文档转换能力
DICOMDoconut.NET8.DicomDicom医学图像查看（.dcm — 仅插件格式）

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

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

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

text
builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // implements IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // optional default config
});

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

要点

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

此页面有帮助吗？