插件系统

通过插件扩展查看器

Doconut 的核心保持精简；可选功能以 插件 形式提供 — 独立的 NuGet 包，贡献查看器或服务，并由您的许可证开启。本页解释注册模型、当许可证未覆盖插件时启动时会发生什么，以及如何插入您自己的查看器。

注册插件

每个插件包都会公开一个插件类。请在 Application_Start 中注册一次：

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// 一个已注册的插件如果缺少许可证，会在 Application_Start 这里抛出，且
// 站点随后对每个请求返回一个空的 500。原因记录在 Windows 事件日志中。

AddPlugin<TPlugin>() 创建插件并让它使用 DoconutOptions 注册其贡献。插件的所有贡献都会标记为插件的 必需功能，DoconutHost.Initialize 在站点处理首个请求之前检查每个已注册插件是否符合许可证。

缺少插件许可证会导致站点停止

当没有有效许可证授予已注册插件的功能时 — 完全没有许可证、旧的 TRIAL 文件，或付费许可证缺少该功能 — DoconutHost.Initialize 会从 Application_Start 抛出 InvalidOperationException：

text
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.

在 System.Web 中，Application_Start 中的异常不会生成错误页面。每个请求都会返回空的 500，IIS 日志中没有有用信息，且该消息仅出现在 Windows 事件日志（应用程序日志，来源 ASP.NET）。当站点在添加 AddPlugin 行后立即停止响应时，请首先检查 wwwroot 中的许可证文件 — 参见 许可证设置。

合约

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

csharp
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 和 .ima — DICOM 没有内置查看器）：如果未授权该功能，打开将失败：
text
LicenseException: This document type requires the 'Dicom' plugin license.

有效的临时许可证会授予所有功能。 这是一种经典的上线惊喜：在评估期间运行的相同 AddPlugin 行，在购买的许可证缺少其中某个功能时会导致站点停止。将 IsCapabilityGranted(...) 与部署前购买的内容进行比较。完全没有许可证时，什么也不会被授予 — 缺少许可证并不等同于临时许可证。

相同的门控也会影响浏览器：Viewer.ReferenceScripts() 和 ReferenceCss() 仅在许可证授予时才输出受许可证门控的功能（搜索、注释）的文件，因此页面永远不会提供服务器会拒绝的功能。

功能与插件映射

特性如何启用功能贡献
Annotation内置于查看器；包括注释资源Annotation浏览器创作、会话持久化、嵌入式导出
Search内置于可搜索格式的查看器；包括搜索资源Search原生文本索引、高亮、结果导航
Converter安装 Doconut.NETFramework.Converter 并注册 ConverterPluginConverterC# 转换服务以及可选的网页小部件
DICOM安装 Doconut.NETFramework.Dicom 并注册 DicomPluginDicom针对 .dcm 和 .ima 的医学图像查看

Annotation 和 Search 不使用 AddPlugin<TPlugin>()。Converter 和 DICOM 各自在 插件 下有一个页面，提供其配置和使用说明。在此包中，DICOM 渲染页面、帧和动画，但不读取技术元数据 — 参见 DICOM 插件。

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

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

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // 实现 IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // 可选的默认配置
});

自定义查看器优先于 所有 — 包括内置和插件 — 并且不受许可证门控：它们是您的代码。当您未提供默认配置时，工厂会使用 ImageConfig。

要点

  • 插件在 DoconutHost.Initialize 中显式注册，并在此处验证其功能；缺少授权会导致站点以空的 500 停止，原因记录在 Windows 事件日志中。
  • 覆盖式插件会优雅降级；仅插件支持的格式会因 LicenseException 而失败。
  • 有效的临时许可证会解锁所有功能；正式环境仅解锁已购买的功能。发布前请使用 IDoconutLicenseService 进行检查。

此页面对您有帮助吗？