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

既存の Doconut.NET6 アプリケーションを現在の DI と非同期 API に移行する

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

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

プロジェクトに含まれる場合…世代
app.MapWhen(... "DocImage.axd" ...)レガシー / クラシック
new Viewer(_cache, _accessor, ...)レガシー / クラシック
Viewer.DoconutLicense(...) または Viewer.SetLicensePlugin(...)レガシー / クラシック
手動でコピーした docViewer.js、documentLinks.js、または docViewer.UI.jsレガシー / クラシック
builder.Services.AddDoconut(...)現在の統合
app.UseDoconutResources() と app.UseDoconut()現在の統合
Viewer が依存性注入で提供される現在の統合
await viewer.OpenDocumentAsync(...)現在の統合

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

NuGet パッケージ名だけでは判断できない理由

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

このガイドで検証された現在のリリースは 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 を選択しないでください。デフォルトのコマンドは最新の安定版リリースをインストールします:

bash
dotnet add package Doconut.NET6

このガイドで検証されたリリースへの再現可能な移行のために、バージョンを別のオプションとして指定してください:

bash
dotnet add package Doconut.NET6 --version 26.9.0

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

text
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 を構築します:

csharp
// クラシック統合 — 比較のみ; 現在の SDK に対してコンパイルしないでください。
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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

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

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

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

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

csharp
// クラシック統合 — カットオーバー中に削除。
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

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

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

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

ビューアの構築とライフタイム

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

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

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

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

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

csharp
// 現在の .NET 6 統合: Viewer は DI から取得され、ドキュメントのオープンは非同期です。
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

csharp
viewer.CloseDocument(token);

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

構成クラス

現在の API は関心事を分離します:

関心事現在の型
ミドルウェア パス、ライセンス、プラグイン登録DoconutOptions
パスワード、タイムアウト、セキュリティ、透かしDocOptions
フォーマットのレンダリングと DPIPdfConfig、WordConfig、ExcelConfig、およびその他の BaseConfig タイプ
ブラウザー ウィジェットのデフォルトViewerConfig または同等の JavaScript オプション
生成された CSS とスクリプトCssConfig および ScriptConfig

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

ビューア ツールバー、検索、注釈

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

  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 のリボンは埋め込まれた機能制御リソースです。

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

プラグイン登録

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

csharp
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 セッションを構成する必要があります:

csharp
builder.Services.AddDistributedMemoryCache(); // session state はキャッシュが必要です (MVC/Razor Pages はすでに追加されています)
builder.Services.AddSession();
app.UseSession();

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

Distributed リファレンスアプリケーションはアクセスチケットと転送詳細を追加します。これらの API は通常のシングルノード移行には必要ありません。

移行のテスト

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

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

ロールバック計画

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

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

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

旧ドキュメント

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

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

このページは役に立ちましたか?