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

はじめに

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

抽象的な文書フォーマットが変換パイプラインを通じて1つの正規化された出力へ流れる様子

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.Viewer.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 ドキュメントを参照して、最新の製品情報と統合情報をご確認ください。