Doconut のドロップインコンバータウィジェットを .NET 8 で有効にする
.NET 8 で Doconut のドロップインコンバータウィジェットを登録して有効化する
ドロップインウィジェットは、ファイルのアップロード、変換の実行、結果のダウンロードを行うための Doconut が提供する既成の UI です。
デフォルトではウィジェットの 3 つの ?convert= エンドポイントは 404 を返します。これらは Converter プラグインを登録し、AddConverterWidget() を DoconutOptions で呼び出したときにのみ有効になります。
以下は、両方の要件を満たす完全なコピー＆ペースト可能なスタートアップ構成です。
1. 前提条件 – ライセンスとセッションサポート
- ライセンス – Converter プラグインは
Converter機能を付与するライセンスが必要です。ファイル（例:Doconut.Viewer.lic）をアプリからアクセス可能な場所に配置し、DoconutOptions.LicensePathをそのパスに設定してください。 - セッション状態 – Doconut のセキュリティモデルはドキュメントセッショントークンを ASP.NET Core のセッションに保存します。分散キャッシュを追加し、ミドルウェアが接続される前に
AddSession()を実行してください。
builder.Services.AddDistributedMemoryCache(); // セッションに必要です
builder.Services.AddSession(); // IDistributedCache‑バックエンドのセッションを有効にします
2. コア Doconut サービスの登録
AddDoconut() は、ビューア、ライセンスサービス、プラグインレジストリを注入する唯一のエントリーポイントです。
builder.Services.AddDoconut(options =>
{
// Doconut にライセンス ファイルの場所を伝えます。
options.LicensePath = "Doconut.Viewer.lic";
// Converter プラグインを登録します – これによりライセンス機能も検証されます。
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});
ライセンスに Converter 機能が 含まれていない 場合、上記の呼び出しは InvalidOperationException をスローし、アプリケーションは起動しません。この早期失敗の動作により、ライセンス違反のビルドをデプロイすることを防げます。
3. AddConverterWidget でウィジェットを有効化する
ウィジェットはオプトイン方式です。AddConverterWidget() を呼び出すことで、3 つの変換エンドポイント（?convert=open、?convert=run、?convert=download）が登録され、クライアント側の設定（最大アップロードサイズ、ベースパスなど）が少量接続されます。
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
// ドロップ‑イン UI を有効にし、クライアント側のアップロード制限を設定します。
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25; // クライアントの事前チェック; サーバーは独自の制限を強制します
});
});
エンドポイントを作成するのは AddConverterWidget の呼び出しだけです。静的 JavaScript ファイル（doconutConverter.js）は常に埋め込みリソースとして配信されますが、エンドポイントが存在しない場合はサーバーへの接続に失敗します。
4. ミドルウェアを正しい順序で接続する
静的アセットを提供するミドルウェア（UseDoconutResources）は、ターミナルビューアミドルウェア（UseDoconut）より 前に 実行される必要があります。Doconut は各リクエストでセッションを検証するため、セッションミドルウェアも早い段階で配置する必要があります。
app.UseSession(); // UseDoconut() の前に実行する必要があります
app.UseDoconutResources(); // JS、CSS、画像を提供します
app.UseDoconut(); // ?convert= とドキュメントページのリクエストを処理します
このパイプラインが整うと、/doconut-res/doconutConverter.js へのリクエストが成功し、ウィジェットは /doconut?convert=open、/doconut?convert=run、/doconut?convert=download を呼び出すことができます。
5. ウィジェットの実際の動作
| フェーズ | サーバーエンドポイント | 典型的なレスポンス |
|---|---|---|
| オープン | ?convert=open | token、ページ数、ソース拡張子、許可されたターゲット形式のリストを含む JSON ペイロードを返します。 |
| 実行 | ?convert=run | 変換を開始し、downloadToken、結果ページ数、推奨ファイル名、出力に透かしが付いているかを示すフラグを返します。 |
| ダウンロード | ?convert=download | クライアントが提供されたダウンロード URL に従うと、変換されたファイルをストリーム配信します。 |
クライアント側では、ウィジェットは widget.MaxUploadMb に対して事前アップロードサイズチェックを行います。ファイルがその上限を超えると、ウィジェットはアップロードを中止し、onError コールバックを phase = "open" とフレンドリーなメッセージと共に発火させます。サーバーは独自の上限を強制し、クライアントチェックをすり抜けたリクエストに対しては 413 Payload Too Large で応答します。
6. ウィジェットイベントへのフック（C# 側は不要）
すべてのコールバック（onReady、onSourceLoaded、onConverted、onError など）は、ウィジェットをホストするページが提供する JavaScript 関数です。質問は 登録 側に焦点を当てているため、これらのコールバックを処理するための追加の C# コードを書く必要はありません。エンドポイントが有効になると、ウィジェットが自動的に呼び出します。
7. よくある落とし穴と回避策
| 症状 | 考えられる原因 | 対策 |
|---|---|---|
404 on /doconut?convert=open | AddConverterWidget() が省略されました。 | セクション 3 に示した呼び出しを追加してください。 |
機能が不足していることを示す InvalidOperationException が原因でアプリケーションの起動に失敗します | ライセンスファイルが Converter を付与していません。 | Converter 機能を含むライセンスを取得してください。 |
Session‑related 500 error | UseSession() が UseDoconut() の後に配置された、またはキャッシュ登録が欠如している。 | app.UseSession() が app.UseDoconut() の前に実行され、キャッシュサービスが登録されていることを確認してください。 |
8. アプリを実行してウィジェットの動作を確認する
- ASP.NET Core プロジェクトをビルドして実行します。
<div id="doconut-convert"></div>要素を含み、Doconut コンバータスクリプトを組み込んだページを開きます（スクリプトは/doconut-res/doconutConverter.jsから自動的に配信されます）。- 対応ファイル（PDF、DOCX、DWG など）をドロップ領域にドラッグします。
- ウィジェットは
?convert=openを呼び出し、次に?convert=runを呼び出し、最後に?convert=downloadを指す Download リンクを表示します。
3 つのエンドポイントが 404 ではなく JSON で応答すれば、ウィジェットは正しく登録されており、本番環境で使用できる状態です。
次のステップ: 上記のコードスニペットを Program.cs（または Startup.cs）に追加し、ライセンスファイルが存在することを確認してアプリを起動してください。ドロップインコンバータウィジェットは、サーバー側の追加変更なしで利用可能になります。