クラシック .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() の組み合わせ現在の統合
DI によって提供される Viewer現在の統合
await viewer.OpenDocumentAsync(...)現在の統合

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

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

bash
dotnet add package Doconut.NET6

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

bash
dotnet add package Doconut.NET6 --version 26.7.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 を個別にテストしてください。

起動と依存性注入

Classic applications construct Viewer with ASP.NET cache and request-accessor dependencies:

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

現在の統合では Doconut を 1 回だけ登録し、依存性注入から 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 インスタンス自体は所有しません。

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

Remove the classic MapWhen branch that detects DocImage.axd:

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

In the current pipeline:

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

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

Viewer の構築とライフタイム

Remove application-owned caches of Viewer objects. Inject Viewer into an endpoint, Razor page, controller, or scoped application service:

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

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

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

Replace synchronous OpenDocument(...) with OpenDocumentAsync(...):

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

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

csharp
viewer.CloseDocument(token);

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

設定クラス

The current API separates concerns:

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

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

Viewer ツールバー、検索、注釈

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

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

プラグイン登録

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

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(); // セッション状態にはキャッシュが必要です (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 へはリダイレクトされません。

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