プラグインシステム

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

Doconut のコアは軽量に保たれています。オプション機能は プラグイン として提供され、ビューアやサービスを提供する個別の NuGet パッケージで、ライセンスに応じて有効化されます。このページでは登録モデル、ライセンスがプラグインをカバーしていない場合の起動時の挙動、そして独自のビューアをプラグインする方法を説明します。

プラグインの登録

各プラグイン パッケージは 1 つのプラグイン クラスを公開します。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 のイベントログ(Application ログ、ソース ASP.NET)にのみ表示されます。AddPlugin 行を追加した直後にサイトが応答しなくなった場合は、まず wwwroot のライセンスファイルを確認してください — ライセンス設定 を参照。

契約

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

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 ライセンスはすべての機能を付与します。 これは典型的な本番稼働時のサプライズです。評価期間中に実行された同じ AddPlugin 行が、購入したライセンスにその機能が含まれていない場合にサイトを停止させます。デプロイ前に購入した内容と IsCapabilityGranted(...) を比較してください。ライセンスが全くない場合、何も付与されません — ライセンスが欠如していることは Temporary ライセンスではありません。

同じゲーティングがブラウザにも適用されます:Viewer.ReferenceScripts() と ReferenceCss() は、ライセンスが付与した場合にのみ、ライセンス制御された機能(Search、Annotation)のファイルを出力します。したがって、ページはサーバーが拒否する機能を提示することはありません。

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

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

注釈 と 検索 は AddPlugin<TPlugin>() を使用しません。Converter、DICOM、Signer にはそれぞれ プラグイン 配下に設定と使用方法のページがあります。このパッケージでは、DICOM はページ、フレーム、アニメーションをレンダリングしますが、技術メタデータは読み取らない — DICOM プラグイン を参照してください。

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

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

csharp
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 で失敗します。
  • 有効な Temporary ライセンスはすべてをアンロックし、プロダクションでは購入したものだけがアンロックされます。出荷前に IDoconutLicenseService で確認してください。

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