コンバータープラグイン

ConverterプラグインはDoconutをドキュメント変換サービスに変えます。パブリックな DocumentConverter ファサードの背後にあるエンジンを提供し、オプトインで独自のHTTP契約を持つドロップインウィジェットも提供するので、C# から、ウィジェットから、または自分で作成したフロントエンドからドキュメントを変換できます。

パッケージのインストール

最新の安定版Converterプラグインをインストールします:

dotnet add package Doconut.NET8.Converter

プラグインを現在の 26.7.0 リリースに固定するには、バージョンを別途指定します:

dotnet add package Doconut.NET8.Converter --version 26.7.0

Converterパッケージは Doconut.NET8 と同じバージョンに保ってください。パッケージIDは Doconut.NET8.Converter です。.26.7.0 はダウンロードされた .nupkg ファイル名にのみ現れます。

プラグインの登録

AddConverter() メソッドは存在しません — Doconut のプラグインモデルは統一されています。すべてのプラグインは、Converter も含めて、同じ方法で登録されます：AddDoconut() 内で AddPlugin<TPlugin>() を呼び出します。ConverterPlugin は独自の NuGet パッケージ Doconut.NET8.Converter として提供され、ベースビューアーパッケージと共にインストールされます。

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

この呼び出しは、ライセンスが欠如している場合、レガシーな TRIAL ファイルがある場合、または Converter 機能を付与しない一時的でないライセンスの場合、起動時に例外をスローします — AddDoconut() 内部から発生した InvalidOperationException です。アプリがリクエストを処理する前に発生します。 一時的なデモ/NFR 登録は受け付けられます；期限が切れた後も、透かし付き出力で変換は利用可能です。サイレントな無料ティアはありません。ライセンスのロード方法については License Setup を参照してください。

C# から変換

すべての変換は、位置が0に設定されたシーク可能な MemoryStream を返し、すぐに読み取りまたはコピーできます。必要な場所で DI から DocumentConverter を解決してください — 設計上ステートレスなので、単一インスタンスをリクエスト間で安全に再利用できます。

// DocumentConverter を注入します。そのコンストラクタは internal なので、決して `new` しないでください。
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension には先頭のドットが含まれます。password は、ドキュメントが保護されていない限り null です。
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

間違えやすい2つの詳細があります：ストリームオーバーロードの sourceExtension では先頭のドット（".xlsx"、"xlsx" ではなく）を含める必要があります — コンバータはそれをフォーマットカタログと照合し、ドットなしの拡張子では解決できません。また、名前に反して WordToHtmlAsync は Task<string> ではなく Task<Stream> を返します — HTMLドキュメント（画像はBase64で埋め込まれた）をストリームとして取得でき、他のすべての変換結果と同様です。

対象フォーマット

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

すべてのソースがすべてのターゲットに変換できるわけではありません — プラグインは各ソースのフォーマットファミリー（Word、Excel、PowerPoint、PDF、CAD、Image、Email、Diagram、Project/Task、PSD、Webドキュメント）を独自の固定された許可対象セットにマッピングします。この enum を UI のターゲットリストとしてハードコードしないでください：?convert=open はアップロードされたファイルに対する実際の allowedTargets を返し、それがピッカーの駆動要素となります。

ドロップインウィジェット

ウィジェットの ?convert=open|run|download エンドポイントはオプトイン方式で、デフォルトでは無効化されています — デフォルトで安全です。サーバー側で有効化し、プラグインの登録と併せて行います:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

AddConverterWidget() がない場合、3つの ?convert= エンドポイントは 404 を返します — しかし、JS ファイル自体は引き続き配信されます（これは単純な埋め込み静的リソースであり、通信するエンドポイントだけが制限されています）。AddConverterWidget() は依然として Converter プラグインの登録と、Converter を付与するライセンスが必要です — それ自体では変換権限を付与しません。

ウィジェットのカスタマイズ

Doconut.convert(selector, options) に渡される初期オプション:

コールバック:

Doconut.convert() はウィジェットインスタンス自体を返します — それを保持してウィジェットをプログラムから操作してください:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // アイドル/ドロップ画面に戻ります; onReady は再度発火しません
conv.loadFile(file);  // File オブジェクトでフローを開始します; 現在アイドル状態でない限り何もしません
conv.destroy();       // リスナーを削除し、mount を空にします; これ以降インスタンスは使用できません

独自フロントエンドの構築

ウィジェットはこの HTTP 契約のクライアントに過ぎません — 別の UX のために直接これに対して独自のフロントエンドを構築してください。3 つのルートはすべて UseDoconut() がマウントされている ASP.NET ブランチの下にあります（通常は /doconut）。

アップロードされたソースバイトはサーバー側に 30 分の TTL で保管されます；その期間が過ぎると、run は 404 を返し、ファイルは再度開く必要があります。変換結果は同じ保管領域に残ります — 変換が完了すると downloadToken は新たな 30 分間のウィンドウを取得します — 一方、resultToken は通常のビューアセッショントークンで、ビューアのセッションキャッシュに従い、保管領域とは独立しています。

sourceExt は open 応答内では先頭にドットがありません（例: "docx"） — これは DocumentConverter.ConvertAsync の sourceExtension パラメータとは逆の慣例で、こちらはドットが必要です。

失敗モード（ルート別）:

リソース所有権

コンバータはゼロ位置に設定されたシーク可能な MemoryStream を返します。呼び出し側がそのストリームを所有し、コピーまたは内容を返した後に破棄すべきです。DocumentConverter サービス自体はステートレスで、依存性注入から解決されます。サービスを手動で構築したり破棄したりしないでください。

Web ウィジェットでは、アップロードとダウンロードのスタッシュはそれぞれ独立した 30 分の TTL を持ちます。代わりに、ビューア resultToken はビューアセッションの有効期間に従います。ビューア結果を閉じても、まだ有効なダウンロードスタッシュは削除されず、ブラウザウィジェットをリセットしてもいずれの TTL も延長されません。

トラブルシューティング

ウォーターマーキング

ConverterPlugin が登録されている場合、ホストのライセンスは次の 3 つの状態のいずれかです：

両方の呼び出しパスは同じルールからフラグを計算します：DocumentConverter の C# ファサードはライセンスの IsViewerLicensed と IsTemporary の状態から内部的に導出し、ウィジェットの ?convert=run ハンドラは同等のチェック（IsViewerLicensed && !IsTrial && !IsTemporary）を行い、返す watermarked フィールドを埋めます。統合は購入前に評価ライセンスでエンドツーエンドに構築・テストでき、変更されるのは出力バイトだけです。