コンバータプラグイン

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

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

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

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

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

プラグインの登録

AddConverter() メソッドは存在しません — Doconut のプラグインモデルは統一されています。コンバータを含むすべてのプラグインは同じ方法で登録されます：AddDoconut() の内部で AddPlugin<TPlugin>() を呼び出します。ConverterPlugin は独自の NuGet パッケージ Doconut.NETStandard.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 から取得してください — 設計上ステートレスなので、単一インスタンスをリクエスト間で安全に再利用できます。

viewer.Converter.GetConverter() はここには存在しません。変換はビューアインスタンスを介して行われず、代わりに Doconut.DocumentConverter をインジェクトしてください。

// 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);

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

対象フォーマット

ConversionTarget（名前空間 Doconut.Configs.Conversion）には 45 のメンバーがあります:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

この単一の enum はすべてのソースファミリーをカバーします。以前のライブラリではファミリーごとに *ConfigConverter 型（WordConfigConverter、ExcelConfigConverter など）があり、各々に独自の入れ子 EnTargetFormat enum があり、入力用に SourceFormatConverter enum がありました。これらはすべて廃止されました；移行ガイド を参照してください。

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

Drop-inウィジェット

ウィジェットの ?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();         // back to the idle/drop screen; does not re-fire onReady
conv.loadFile(file);  // starts the flow with a File object; no-op unless currently idle
conv.destroy();       // removes listeners, empties the mount; the instance is unusable after this

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

ウィジェットはこの 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 フィールドを設定します。統合は購入前に評価ライセンスでエンドツーエンドに構築・テストでき、変更されるのは出力バイトだけです。