插件系统
通过插件扩展查看器
Doconut 的核心保持精简;可选功能以 插件 的形式提供——独立的 NuGet 包,贡献查看器或服务,并由您的许可证启用。本页解释注册模型、当许可证未覆盖插件时启动时会发生什么,以及如何插入您自己的查看器。
注册插件
每个插件包公开一个插件类。请在 Application_Start 中注册一次:
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:
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 中的许可证文件——参见 许可证设置。
合约
插件实现了一个刻意简小的接口:
public interface IDoconutPlugin
{
string Name { get; } // 例如 "Doconut DICOM Viewer"
LicenseCapability RequiredCapability { get; } // 许可证入口
void Register(IDoconutPluginBuilder builder); // 贡献查看器/服务
}在 Register 中,构建器接受两种类型的贡献:
builder.RegisterViewer(extension, factory)— 用于文件扩展名的查看器;工厂返回一个IFormatViewer(DICOM 插件以这种方式注册.dcm和.ima),builder.RegisterService<TContract>(() => …)— 供管道其他部分查找的类型化服务。
功能和门控
功能是许可证的计量单位。Converter、Dicom 和 Signer 作为可选插件提供;Search 和 Annotation 是以相同方式受门控的内置功能。基础查看器 不是 功能——它是前置条件,在许可证服务上以 IsViewerLicensed 形式公开。
启动验证通常会将未授权的插件排除在请求管道之外。查看器工厂还会应用两条防御性规则,当站点运行期间授权发生变化时这些规则会生效:
- 覆盖内置查看器的插件(它声明了一个内置查看器也处理的扩展名):如果已授权该功能,插件的查看器优先;如果未授权,Doconut 将回退到内置查看器。用户仍然可以看到文档,只是不会获得插件的行为。
- 仅插件支持的格式(
.dcm和.ima—— DICOM 没有内置查看器):如果未授权该功能,打开将失败:
LicenseException: This document type requires the 'Dicom' plugin license.有效的临时许可证会授予所有功能。 这是一种经典的上线惊喜:在评估期间运行的相同 AddPlugin 行在购买的许可证缺少其中某项功能时会导致站点停止。将 IsCapabilityGranted(...) 与部署前购买的内容进行比较。完全没有许可证时,什么也不会被授予——缺少许可证并不等同于临时许可证。
相同的门控也会影响浏览器:Viewer.ReferenceScripts() 和 ReferenceCss() 会在许可证授予时 仅 发出受许可证限制的功能(搜索、注释)的文件,因此页面永远不会提供服务器会拒绝的功能。
功能和插件映射
| 功能 | 启用方式 | 功能 | 贡献 |
|---|---|---|---|
| 注释 | 内置于查看器;包括注释资源 | Annotation | 浏览器创作、会话持久化、嵌入式导出 |
| 搜索 | 内置于可搜索格式的查看器;包括搜索资源 | Search | 本地文本索引、突出显示、结果导航 |
| 转换器 | 安装 Doconut.NETFramework.Converter 并注册 ConverterPlugin | Converter | C# 转换服务以及可选的网页小部件 |
| DICOM | 安装 Doconut.NETFramework.Dicom 并注册 DicomPlugin | Dicom | 用于 .dcm 和 .ima 的医学图像查看 |
| 签名器 | 安装 Doconut.NETFramework.Signer 并注册 SignerPlugin | Signer | 针对 PDF 和 Word 的可见签名和数字印章:C# 签名服务以及可选的网页小部件 |
注释和搜索不使用 AddPlugin<TPlugin>()。转换器、DICOM 和签名器各自都有一个位于 插件 下的页面,提供其配置和使用方法。在此包中,DICOM 渲染页面、帧和动画,但不读取技术元数据——参见 DICOM 插件。
自定义查看器 — 您自己的格式处理器
您可以在 Application_Start 中直接将查看器插入管道,而无需编写插件包:
Doconut.DoconutHost.Initialize(options =>
{
options.RegisterViewer(
".myext",
() => new MyCustomViewer(), // 实现 IFormatViewer
() => new ImageConfig { ImageResolution = 150 }); // 可选的默认配置
});
// 工厂创建的格式处理器。用您自己的渲染替换这些成员。
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
public ViewerType ViewerType => ViewerType.None;
public int TotalPages => 0;
public int DefaultWidth => 0;
public int DefaultHeight => 0;
public bool PreferOcr => false;
public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
=> Task.CompletedTask;
public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
=> Task.FromResult(Array.Empty<byte>());
public void Dispose() { }
}自定义查看器优先于 所有内容 —— 包括内置和插件 —— 并且不受许可证门控:它们是您的代码。当您未提供默认配置时,工厂会使用一个 ImageConfig。
要点
- 插件在
DoconutHost.Initialize中显式注册,并在此处验证其功能;缺少授权会导致站点以空的500停止,其原因记录在 Windows 事件日志中。 - 覆盖式插件会优雅降级;仅插件支持的格式会因
LicenseException而失败。 - 有效的临时许可证会解锁所有功能;正式环境仅解锁您购买的功能。发布前请使用
IDoconutLicenseService进行检查。
此页面对您有帮助吗?