プラグインシステム

プラグインでビューアを拡張する

Doconut のコアは軽量に保たれ、オプション機能は プラグイン として提供されます — ビューアやサービスを提供する別個の NuGet パッケージで、ライセンスによって有効化されます。このページでは、登録モデル、ランタイムでのライセンスゲーティングの動作、そして独自のビューアをプラグインする方法を説明します。

このモデルは本リリースで新しく導入されました。以前の .NET Standard ライブラリにはプラグインレジストリがなく、変換はビューア自体に組み込まれ、プラグインライセンスは静的な Viewer.SetLicensePlugin(...) 呼び出しでインストールされていました。ここではどちらも登録メカニズムではありません。

プラグインの登録

各プラグインパッケージは 1 つのプラグインクラスを公開します。起動時に一度だけ登録します。

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

AddPlugin<TPlugin>() はプラグインをインスタンス化し、DoconutOptions に保持されているプラグインレジストリに対してその Register コールバックを呼び出します。プラグインが提供するすべてはプラグインの 必須機能 でタグ付けされます。AddDoconut() は登録されたプラグインを即座に検証します:ライセンスが欠如している、レガシーな TRIAL ファイルがある、または機能がない有料ライセンスの場合、InvalidOperationException で起動が失敗します。Temporary/Demo 登録は有効期限が切れるまで保持されますが、期限後はランタイム機能が取り消されます。

契約

プラグインは意図的に小さなインターフェースを実装します。

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // 例: "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // ライセンスゲート
    void Register(IDoconutPluginBuilder builder); // ビューア/サービスを提供する
}

Register の内部では、ビルダーは 2 種類の貢献を受け入れます:

  • builder.RegisterViewer(extension, factory) — ファイル拡張子用のビューア;ファクトリは IFormatViewer を返します(DICOM プラグインはこの方法で .dcm と .ima を登録します)。
  • builder.RegisterService<TContract>(() => …) — パイプラインの他の部分が参照できる型付きサービス。

機能とゲーティング

機能はライセンス単位です。Converter、Dicom、Signer はオプトインプラグインとして提供され、Search と Annotation は同様にゲートされる組み込み機能です。ベースビューアは 機能ではなく — 前提条件であり、ライセンスサービス上で IsViewerLicensed として公開されます。

起動時の検証は通常、ライセンスのないプラグインがリクエストパイプラインに入るのを防ぎます。ビューアファクトリはさらに 2 つの防御的ランタイムルールを適用します。これは起動後に権利が変更された場合に重要です:

  • プラグインが組み込みビューアを上書きする(プラグインが組み込みレジストリでも処理される拡張子を要求する場合):機能がライセンスされていればプラグインビューアが優先されます;ライセンスがない場合、Doconut は静かに組み込みビューアにフォールバックします。ユーザーは依然としてドキュメントを見ることができますが、プラグイン機能は利用できません。
  • プラグイン専用フォーマット(.dcm と .ima — DICOM には組み込みビューアがありません):機能がない場合、オープン呼び出しは即座に失敗します:
text
LicenseException: This document type requires the 'Dicom' plugin license.

有効な Temporary ライセンスはすべての機能を付与します(クリーンで透かしのないベースビューイングが可能)。これは本番稼働時の典型的な驚きの原因です:機能の一つが欠如した購入済みライセンスで同じプラグインを登録すると、AddDoconut() が起動時に失敗します。デプロイ前に IsCapabilityGranted(...) をプランと比較してください。逆に、ライセンスが全くない場合、何も付与されません — ライセンスが欠如していることは Temporary ライセンスではありません。

同じゲーティングはクライアント側でも現れます:Viewer.ReferenceScripts() と ReferenceCss() は、ライセンスで有効化された機能(検索、注釈、…)のスクリプト/スタイルバンドルを ライセンスが有効なときだけ 発行し、ウィジェットの UI がサーバーの実際の挙動と一致し続けます。

機能とプラグインのマップ

製品 UI では「プラグイン」を広い機能ラベルとして使用しますが、サーバー側の登録は異なります:

機能有効化方法機能貢献内容
注釈ビューアに組み込まれ、注釈リソースを含むAnnotationブラウザでの作成、セッション永続化、そして焼き込みエクスポート
検索検索可能なフォーマットビューアに組み込まれ、検索リソースを含み、必要に応じて抽出を有効化Searchネイティブテキストインデックス、ハイライト、結果ナビゲーション
コンバータDoconut.NETStandard.Converter をインストールし、ConverterPlugin を登録ConverterC# 変換サービスとオプションのウェブウィジェット
DICOMDoconut.NETStandard.Dicom をインストールし、DicomPlugin を登録Dicom医療画像ビューア(.dcm と .ima 用)
サイナーDoconut.NETStandard.Signer をインストールし、SignerPlugin を登録SignerPDF と Word の可視署名とデジタルシール:C# 署名サービスとオプションのウェブウィジェット

注釈と通常の検索は AddPlugin<TPlugin>() を使用しません;それらのバンドルは対応する機能がライセンスで付与されたときだけ発行されます。コンバータ、DICOM、サイナーはオプトイン IDoconutPlugin 実装です。

リリースされたプラグインパッケージ

プラグインパッケージ機能貢献内容
コンバータDoconut.NETStandard.ConverterConverterドキュメント変換機能
DICOMDoconut.NETStandard.DicomDicom医療画像ビューア(.dcm と .ima — プラグイン専用フォーマット)
サイナーDoconut.NETStandard.SignerSignerPDF と Word の署名

それぞれは Plugins の下に専用ページがあり、構成と使用方法が記載されています。

カスタムビューア — 独自のフォーマットハンドラ

プラグインパッケージを書かずに、Program.cs から直接ビューアをパイプラインに組み込むことができます:

csharp
builder.Services.AddDoconut(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 にフォールバックします。

まとめ

  • プラグインは明示的に登録され、その LicenseCapability は AddDoconut() 中に検証されます — 欠如または一時的でない権利が不十分な場合は速やかに失敗します。
  • 上書きスタイルのプラグインは優雅に劣化し、プラグイン専用フォーマットは LicenseException で失敗します。
  • 有効な Temporary ライセンスはすべてを解放し、プロダクション環境では購入したものだけが解放されます。出荷前に IDoconutLicenseService で確認してください。

このページは役に立ちましたか?