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

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

Which .NET 6 integration are you using?

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

Why the NuGet package name may not tell you

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

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

Before you migrate

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

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

Package and license compatibility

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

dotnet add package Doconut.NET6

このガイドで監査されたリリースに対して再現性のある移行を行うには、バージョンを別オプションとして渡します。

dotnet add package Doconut.NET6 --version 26.7.0

すべての Doconut プラグインはコアパッケージと同じバージョンに保ちます。現在の統合は AddDoconut() 時にライセンスを 1 回だけ読み込み、次の優先順位で処理します。

LicenseStream > LicenseContent > LicensePath > automatic discovery

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

古いプラグインライセンスが現在のプラグインビルドの権利を保証するとは限りません。Viewer、Search、Annotation、Converter、DICOM をそれぞれ承認されたリリースアーティファクトで個別にテストしてください。

Startup and dependency injection

クラシックアプリケーションは ASP.NET のキャッシュとリクエストアクセサ依存性で Viewer を構築します。

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

現在の統合は Doconut を 1 回だけ登録し、DI から Viewer を取得します。

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

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

Viewer はトランジェントサービスです。ドキュメントセッションマネージャーとそのキャッシュが長期間のドキュメント状態を保持し、特定の注入された Viewer インスタンスは保持しません。

Middleware and resource routing

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

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

Viewer construction and lifetime

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

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

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

Opening and closing documents

同期的な 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 を通じて各ドキュメントを再度オープンします。

Configuration classes

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

DocOptions.ImageResolution をレンダリング制御として持ち越さないでください。これは廃止予定であり、フォーマット固有の設定である BaseConfig.ImageResolution を使用します。すべてのデフォルトを確認し、クラシック設定が同じ動作をするとは想定しないでください。

Viewer toolbar, Search, and Annotation

古いスクリプトを 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 が出力するリソースで現在のページが正しく動作することを確認した後に削除してください。

Plugin registration

クラシックな静的プラグイン・ライセンスメソッドは現在のプラグインを登録しません。リリースされた各パッケージを明示的にインストールし、登録してください。

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

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

Session and document security

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

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

DocOptions.IsSecured = true を保持してください。設計上のレビューで別の要件が出た場合を除き、UnsafeMode = true を移行のショートカットとして使用しないでください。トークンなし、破損トークン、期限切れトークン、別ブラウザーセッションからのトークンでリクエストをテストしてください。

Distributed リファレンスアプリケーションはアクセスチケットと転送詳細を追加しますが、単一ノードの通常移行には必須ではありません。

Testing the migration

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

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

Rollback plan

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

カットオーバー前に以下を文書化してください。

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

Legacy documentation

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

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