コンバータプラグイン

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 のプラグインモデルは統一されています。すべてのプラグインは同じ方法で登録されます: 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 の一時ライセンスは受け付けられ、期限が切れた後も透かし付き出力で変換は利用可能です。無料のサイレントティアはありません。ライセンスの読み込み方法については ライセンス設定 を参照してください。

C# から変換

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

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
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);

間違えやすいポイントが二つあります: ストリームオーバーロードの sourceExtension には先頭のドット (".xlsx"、"xlsx" ではなく) を含める必要があります — コンバータはこれをフォーマットカタログと照合し、ドットなしの拡張子では解決できません。また、名前に反して WordToHtmlAsync は Task<Stream> を返し、Task<string> ではありません — 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 document）を独自の固定された許可対象リストにマッピングします。この 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 オブジェクトでフロー開始。アイドル時以外は No‑op
conv.destroy();       // リスナーを削除し、マウントを空にする。以後インスタンスは使用不可

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

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

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

open 応答の sourceExt には先頭ドットがありません（例: "docx"） — DocumentConverter.ConvertAsync の sourceExtension パラメータがドットを要求するのとは逆の規約です。

失敗モード（ルート別）

リソースの所有権

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

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

トラブルシューティング

ウォーターマーキング

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

両方の呼び出し経路は同じルールでフラグを算出します: DocumentConverter の C# ファサードは内部でライセンスの IsViewerLicensed と IsTemporary 状態から導出し、ウィジェットの ?convert=run ハンドラも同等のチェック (IsViewerLicensed && !IsTrial && !IsTemporary) を行って watermarked フィールドを設定します。評価ライセンスでエンドツーエンドの統合を構築・テストでき、購入前に動作確認が可能です — 変更されるのは出力バイトだけです。