クラシックな .NET 6 統合からの移行

Doconut には 2 つの異なる .NET 6 統合があります。これらは同じ Doconut.NET6 パッケージ名を使用できるため、パッケージ、スタートアップ、ライセンス、またはブラウザーリソースを変更する前に、アプリケーション内の API から世代を特定してください。

使用している .NET 6 統合はどれですか？

両方の列が同じアプリケーションに存在する場合、移行は未完了とみなしてください。別の世代のリソースやミドルウェアを通じてドキュメントトークンを送信しないでください。

NuGet パッケージ名が必ずしも示さない理由

両世代とも Doconut.NET6 パッケージ ID で提供されています。そのため、パッケージ参照、ロックファイル、またはキャッシュされた .nupkg だけではホスティング API を特定できません。正確なパッケージバージョンを記録し、Program.cs、Viewer の構築、ドキュメントのオープン、ブラウザスクリプトを合わせて確認してください。

このガイドで検証された現在のリリースは Doconut.NET6 26.7.0 です。オプションの公開パッケージは Doconut.NET6.Converter と Doconut.NET6.Dicom で、コアパッケージと同じリリースバージョンに固定されています。

移行前に

1. 既存のアプリケーションのブランチとデプロイ可能なバックアップを作成します。
2. コアおよびプラグインパッケージの正確なバージョンを記録します。
3. すべての DocImage.axd マッピング、new Viewer(...) 呼び出し、ライセンス読み込み呼び出し、コピーされた Doconut スクリプト、カスタムツールバーアクション、ドキュメントオープンエンドポイントを一覧化します。
4. 現在の .lic ファイルとデプロイシークレットをソース管理外に保管します。
5. PDF、Office、画像、CAD、メール、DICOM、検索可能、パスワード保護、注釈付きドキュメントの代表的なセットを取得します。
6. 既存のセッションタイムアウト、セキュリティ動作、フォント、プラットフォーム設定を記録します。

本番環境を変更する前に、まず 1 つの環境で移行を行ってください。現在の統合ではサービスのライフタイム、リクエストルーティング、セッション所有権、クライアントリソースの配信が変更されます。

パッケージとライセンスの互換性

コアパッケージは意図的に置き換えるか更新してください。同一のパッケージ ID に依存して新しい API を選択しないでください。デフォルトコマンドは最新の安定版リリースをインストールします：

dotnet add package Doconut.NET6

このガイドで検証されたリリースへ再現性のある移行を行うには、バージョンを別のオプションとして指定してください：

dotnet add package Doconut.NET6 --version 26.7.0

すべての Doconut プラグインはコアパッケージと同じバージョンに保ってください。現在の統合では AddDoconut() 実行時にライセンスを一度だけロードし、以下の優先順位で処理します：

LicenseStream > LicenseContent > LicensePath > automatic discovery

自動検出は Doconut.Viewer.lic とそれに付随する Doconut.Viewer.<Capability>.lic ファイルを探します。Viewer.DoconutLicense(...) または Viewer.SetLicensePlugin(...) のクラシックな呼び出しは現在のスタートアップメカニズムではありません。ライセンスを DoconutOptions に移動し、自動検出を使用する場合は付随ファイルを一緒に保管し、ライセンス変更後に再起動し、IDoconutLicenseService を通じて機能を検証してください。

古いプラグインライセンスが存在することが、現在のプラグインビルドの権利を保証するものと推測しないでください。承認されたリリースアーティファクトを使用して、Viewer、Search、Annotation、Converter、DICOM を個別にテストしてください。

起動と依存性注入

従来のアプリケーションは、ASP.NET のキャッシュとリクエストアクセサの依存関係を使用して Viewer を構築します：

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

現在の統合では Doconut を一度だけ登録し、依存性注入から Viewer を取得します：

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer は一時的なサービスです。ドキュメントセッションマネージャーとそのキャッシュが長期間存続するドキュメント状態を所有し、特定の注入された Viewer インスタンスは所有しません。

ミドルウェアとリソースルーティング

DocImage.axd を検出する従来の MapWhen ブランチを削除します：

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

現在のパイプラインでは：

1. セッションのセキュリティが有効な間、Doconut の前に UseSession() を呼び出します；
2. UseDoconutResources() を UseDoconut() の前に呼び出します；
3. ResourcesPath、生成されたリソース URL、クライアントの ResPath を一致させたままにします；
4. UseDoconut() をブランチにマッピングする際、そのブランチとクライアントの BasePath を一致させたままにします。

MiddlewarePath は検証済みの設定であり、単独で ASP.NET Core のブランチを作成するものではありません。上記のコンパイルサンプルのシンプルなパイプラインを使用するか、クライアントが一貫して使用する明示的な app.Map("/doconut", branch => branch.UseDoconut()) 設定を使用してください。

Viewer の構築とライフタイム

アプリケーションが所有する Viewer オブジェクトのキャッシュを削除します。エンドポイント、Razor ページ、コントローラ、またはスコープドサービスに Viewer を注入します：

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

返されたトークンはサーバー側のドキュメントセッションを識別します。ベアラークレデンシャルとして扱い、ログに記録したり、永続化したり、分析に使用したりしないでください。

ドキュメントのオープンとクローズ

同期的な OpenDocument(...) を OpenDocumentAsync(...) に置き換えます：

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

現在のオーバーロードはファイルパスまたはストリーム、オプションのフォーマット設定、オプションの DocOptions、およびキャンセルトークンを受け取ります。ブラウザが不要になったらサーバーセッションを明示的に閉じてください：

viewer.CloseDocument(token);

カットオーバー後に従来のトークンを再利用しないでください。現在の API を通じて各ドキュメントを再度開きます。

設定クラス

現在の API は関心事を分離しています：

DocOptions.ImageResolution をレンダリング制御として引き継がないでください。これは廃止予定です。フォーマット固有の設定で BaseConfig.ImageResolution を設定します。従来の設定が同じ動作をすると想定せず、すべてのデフォルトを確認してください。

Viewer ツールバー、検索、アノテーション

古いスクリプトを一つずつ移行しないでください。現在のリファレンスアプリケーションは、完全なページパッケージを構成します：

1. ReferenceCss を使用して Viewer CSS とライセンスされた Search/Annotation CSS を出力します；
2. アプリケーションが所有する Viewer ツールバーをレンダリングします；
3. searchBarMount、annBarMount、および必要な Viewer マウントをレンダリングします；
4. ReferenceScripts を使用して Viewer とライセンスされたモジュールスクリプトを出力します；
5. アプリケーション独自の viewerToolbar.js をロードします；
6. 1つの objViewer を初期化します；
7. ライセンスされた Search と Annotation のリボンを初期化します；
8. 各リボンで attach(objViewer) を呼び出します；
9. ドキュメントを開き、objViewer.View(token) を呼び出します。

Search と Annotation は同じ Viewer に付属するモジュールであり、独立したツールバーではありません。メインツールバーはホストアプリケーションに属し、Search と Annotation のリボンは埋め込まれた機能制御されたリソースです。

documentLinks.js や docViewer.UI.js など手動でコピーした従来のファイルは、ReferenceCss と ReferenceScripts が出力するリソースで現在のページが正常に動作することを確認した後に削除してください。

プラグイン登録

従来の静的プラグインライセンス方式では現在のプラグインが登録されません。リリースされた各パッケージを明示的にインストールし、登録してください：

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() は起動時に登録されたプラグインの機能を検証します。Converter と DICOM は .NET 6 向けにリリースされたプラグインです。Normal Search と Annotation は組み込みのライセンス機能であり、AddPlugin<TPlugin>() パッケージではありません。

セッションとドキュメントのセキュリティ

現在の統合では、ドキュメントを不透明なトークンとキャッシュされたセッションに紐付けます。デフォルトの UnsafeMode = false の場合、UseDoconut() はドキュメントアクセスのセキュリティを追加し、ホストは ASP.NET セッションを構成する必要があります：

builder.Services.AddSession();
app.UseSession();

DocOptions.IsSecured = true を保持してください。設計レビューで別の要件がない限り変更しないでください。UnsafeMode = true をマイグレーションのショートカットとして使用しないでください。トークンがないリクエスト、形式が不正なトークン、期限切れトークン、別のブラウザセッションからのトークンでテストしてください。

Distributed リファレンスアプリケーションはアクセスチケットと転送情報を追加しますが、通常のシングルノードマイグレーションではこれらの API は必要ありません。

マイグレーションのテスト

最低限、以下を検証してください：

• 本番ライセンスとすべての登録プラグインでのアプリケーション起動；
• 選択されたパス下での Viewer の CSS/スクリプトおよびすべてのページ画像リクエスト；
• ドキュメントのオープン、ナビゲーション、ズーム、サムネイル、印刷、明示的なクローズ；
• テキストを含むドキュメントでの検索と、画像のみのファイルが検索不可であること；
• アノテーションのロード、保存、エクスポート、および機能制御；
• Converter のターゲット検出、出力、ダウンロード、透かし状態；
• DICOM のページ、フレーム、アニメーション；.NET 6 の技術メタデータは利用できません；
• パスワード保護されたドキュメント、カスタムフォント、非ラテン文字テキスト、設定されたタイムアウト；
• セッション間トークンの拒否と期限切れセッションの挙動；
• モバイル、ダークモード、そして本番環境のリバースプロキシパス。

ロールバック計画

従来のデプロイアーティファクト、対応するパッケージ、ライセンスファイル、コピーされたブラウザリソースを一緒に保管してください。安全なロールバックはアプリケーション全体の世代を切り替えます。従来のサーバーと現在のスクリプト、または現在のサーバーと従来の DocImage.axd 呼び出しを混在させません。

切り替え前に、以下を文書化してください：

• ロールバックに使用するデプロイスロットまたはアーティファクト；
• データベース/キャッシュへの影響（ある場合）；
• アクティブなドキュメントセッションがどのように無効化されるか；
• ロールバック判断に使用するヘルスチェックとスモークドキュメント；
• 前のパッケージセットと構成を復元できる担当者。

旧ドキュメント

翻訳された従来のマニュアルは レガシー .NET 6 設定 で利用可能です。新しい 従来の統合ゲートウェイ は同じ識別シグナルを説明し、このマイグレーションガイドへリンクしています。

従来のインストールが残っている間は、ブックマークやサポートチケットに歴史的な URL を保持してください。これは別世代を記録したもので、現在の API へはリダイレクトされません。