Doconut を使用した .NET のサーバーサイド文書変換

はじめに

サーバーサイドの文書変換を使用すると、Microsoft Office の自動化や別のオンライン変換サービスにソースを送信することなく、アプリケーションが正規化された出力を生成できます。これにより、文書ポータルやバックグラウンドジョブ、制御されたエクスポートワークフローがシンプルになりますが、ホストアプリケーションは依然としてアクセス制御、ストレージ、保持、監視、結果の配信を管理します。

Doconut の .NET 8 コンバータプラグインは、依存性注入された DocumentConverter サービスを通じて変換機能を提供します。本ガイドでは現在の登録方法と API モデルに焦点を当て、変換をビューアセッションに結び付けることは避けます。

必要なパッケージのインストール

ベースのビューアとコンバータパッケージをインストールします:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

両方のパッケージは同じリリースバージョンで揃えてください。再現性のあるビルドが重要な場合は、プロジェクトファイルでバージョンを固定するか、両コマンドに同じ --version 値を渡します。

コンバータプラグインの登録

プラグインは AddDoconut オプションコールバック内で登録します。別途 AddConverter() のような登録メソッドはありません:

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

アプリケーションはコンバータ機能を許可するライセンスを使用しなければなりません。起動時やライセンスエラーは、バックグラウンドキューに回す前に解決しておき、診断が困難になるのを防ぎます。

C# からファイルを変換する

DocumentConverter を変換リクエストを所有するエンドポイントまたはサービスに注入します。コンバータのコンストラクタは internal であるため、アプリケーションコードから直接インスタンス化しないでください。

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

返されるストリームはシーク可能で、先頭に位置しています。呼び出し側が所有し、コピーまたはコンテンツ返却後に破棄してください。

アップロードされたストリームを変換する

ストリームオーバーロードでは、ソース拡張子（先頭のドットを含む）が必要です。コンバータはこれを使用してソース形式を判別します:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

ファイル名と拡張子は信頼できない入力として扱い、アップロードサイズの上限を設定し、ソースタイプを検証し、リクエストユーザーを認可し、提出されたファイル名をストレージパスとして使用しないようにしてください。

実際の機能に基づくターゲットの選択

プラグインは ConversionTarget 列挙型を公開しますが、すべてのソース形式がすべてのターゲットを生成できるわけではありません。カスタム UI では、アップロードされたソースに対して許可されたターゲットのみを表示し、すべての列挙値をそのまま見せないようにします。

Doconut のオプションコンバータウィジェットを使用する場合、レスポンスに含まれる allowedTargets が現在のファイルに対する真実の情報源となります。

バックグラウンド変換をアプリケーションワークフローとして設計する

コンバータはアプリケーションサービスやキューイングされたワーカーから呼び出すことができます。堅牢なジョブは通常次の要素を含みます:

ソースと希望するターゲットを記録する認証済みリクエスト。
生の認証情報ではなく、アプリケーションジョブ ID を含むキューメッセージ。
認可されたストレージ抽象化を通じてソースを取得するワーカー。
キャンセル可能な境界付き変換操作。
明示的な保持ポリシーを伴う永続的な出力ストレージ。
内部パスや機密例外情報を露出しないステータス更新。

代表的な文書で同時実行性を測定した上で、ワーカー数を決定してください。変換コストはソース形式、文書の複雑さ、フォント、画像、出力ターゲットによって変わります。

セキュリティ主張を明確に保つ

.NET アプリケーション内でコンバータを実行すると、Microsoft Office の自動化や別個のオンライン変換 API が不要になります。ただし、プライバシー、コンプライアンス、削除、暗号化といった属性は自動的に保証されるわけではありません。

これらの属性は、アプリケーションがユーザーをどのように認証し、ソースファイルを取得し、ストレージを構成し、ログを保護し、出力を配布し、一時データや保持データを削除するかに依存します。

運用チェックリスト

Doconut.NET8 と Doconut.NET8.Converter のバージョンを揃える。
サービス構成時に ConverterPlugin を登録する。
依存性注入で DocumentConverter を取得する。
ストリームソースの拡張子に先頭のドットを含める。
ソースと結果のストリームを破棄する。
キャンセルとアプリケーションレベルのファイルサイズ制限を使用する。
すべての組み合わせが動作する前提ではなく、ソース‑ターゲットのサポートを検証する。
代表的なファイルで忠実度とリソース使用量をテストする。
ストレージ、認可、監査、保持の判断はアプリケーションコードに組み込む。

公式の Doconut コンバータプラグイン概要と Doconut ドキュメンテーションを参照し、最新の製品情報と統合方法をご確認ください。