.NET Standard 2.1 への移行

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

バージョンが分岐点です

両世代とも 同じパッケージ ID で公開されています。区別できるのはバージョンだけです：

バージョン番号を上げることがアップグレードです。 インストールする別個のパッケージはなく、互換性シムもありません — 26.8.0 は異なる API 表面です。バージョンを上げた後はコンパイルエラーが発生することが予想されます。このガイドの残りはそれらの一覧です。

どの統合を使用していますか？

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

まずホストフレームワークを確認してください

これは好みではなく、ハードなゲートです。現在のパッケージは netstandard2.1 を対象としています：

.NET Framework は netstandard2.1 ライブラリを参照できません。アプリケーションが .NET Framework 上で動作している場合、ここで止めて代わりに Doconut.NETFramework パッケージを使用してください。26.9.0 以降は .NET Framework 4.7.2 が必要です。このリリースの両方の参照アプリケーションは net8.0 を対象としています。

移行前に

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

本番環境を変更する前に、まず 1 つの環境で移行してください。現在の統合はサービスのライフタイム、リクエストルーティング、セッション所有権、クライアントリソース配信を変更し、さらにファームを運用している場合はページがブラウザーに届く方法も変わります。

1. 名前空間: ほぼすべてがルートに移動しました

設定タイプは 4 つの名前空間に分散していましたが、現在はすべて Doconut にあります。

型名は変更されていません: WordConfig、PdfConfig、ExcelConfig、CssConfig、ScriptConfig、CloudUploadConfig、AzureConfig、CDNConfig、FileShareConfig などはすべてそのままです。ほとんどのファイルでは、編集内容は using 行を 2 行削除するだけです。

Doconut.Configs.Editor（BaseConfigEditor、PdfConfigEditor）は削除され、このパッケージには置き換えがありません。アプリケーションがこれらの型を参照している場合は、別途計画し、今回の移行の一部として扱わないでください。

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

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

dotnet add package Doconut.NETStandard

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

dotnet add package Doconut.NETStandard --version 26.8.0

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

LicenseStream > LicenseContent > LicensePath > automatic discovery

自動検出は Doconut.Viewer.lic とそれに付随する Doconut.Viewer.<Capability>.lic ファイルを探します。従来の静的呼び出し Viewer.DoconutLicense(...) および Viewer.SetLicensePlugin(...) は現在の起動メカニズムではなく、古い Viewer コンストラクタが受け取っていたライセンスパスの List<string> も同様です。ライセンスは DoconutOptions に移動し、自動検出を使用する場合は関連ファイルを一緒に配置し、ライセンス変更後に再起動し、IDoconutLicenseService を通じて機能を検証してください。

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

3. 起動と依存性注入

以前はリクエストごとにビューアを構築し、オプションをミドルウェアに渡していました:

// 以前の統合 — 対照用のみ; 現行 SDK ではコンパイルしないでください。
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

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

builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // スペル変更に注意: UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // セッション状態にはキャッシュが必要 (MVC/Razor Pages は既に追加済み)
builder.Services.AddSession();

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

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

持ち越すべき 3 つのポイント:

• new Viewer(cache, accessor) は廃止されました。 コントローラに Doconut.Viewer を注入するか、Razor ビューで @inject Doconut.Viewer Viewer を使用してください。
• UseDoconutResources() は手動配線 app.UseMiddleware<EmbeddedResourceMiddleware>() に取って代わり、ドキュメントブランチの 前に 実行する必要があります。
• UnSafeMode → UnsafeMode。 1 文字のリネームで、コンパイラが検出します。

UnsafeMode が false の場合、SDK はセッショントークンを元のリクエストと照合するため、AddSession() / UseSession() はパイプラインに残す必要があり、ブランチの前に UseSession() を配置します。

もはや存在しないメソッド

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

UseDoconut() は現在引数を取らなくなりました。MapWhen のブランチ形状自体は変更不要です — ただし内部のミドルウェアだけを置き換えます:

app.UseDoconutResources();   // ブランチの **前** に配置

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

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

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

MiddlewarePath は検証済み設定であり、単独で ASP.NET Core のブランチを生成するものではありません。

5. Viewer の構築とライフタイム

アプリケーションが所有する Viewer オブジェクトのキャッシュを削除します。Viewer には保持すべきものは何も残っていません。ドキュメント状態を保持せず、セッションキャッシュがリクエストの存続期間を超えるすべてを所有します。エンドポイント、Razor ページ、コントローラー、またはスコープド アプリケーションサービスに注入してください：

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

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

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

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

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

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

viewer.CloseDocument(token);

InitCache() の呼び出しとそれを保護するフラグをすべて削除します — 手動でウォームアップするものはありません。切り替え後に以前のライブラリで作成されたトークンを再利用しないでください。現在の API を通じて各ドキュメントを再度オープンしてください。

7. Web farm → distributed: 最大の変更点

UseDoconutWebFarm と WebFarmOptions はもはや存在しません。 アプリがそれらを呼び出す場合、このセクションがアップグレード手順です。呼び出さない場合は §8 に進んでください。

以前は 1 つのミドルウェアがすべてを担当していました：共有フォルダーから事前レンダリングされた画像を配信し、別のノードがまだ書き込み中である間 ポーリング していました。

// 以前の統合 — 1 回の呼び出しで、ファイルシステムを介した暗黙的な調整。
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

同じ作業は現在、2 つの明示的な半分に分割されています。書き込み側 — ドキュメントをオープンするノードが、全アーティファクトセット（ページ、ドキュメント情報、検索インデックス、メタデータ）を共有領域に公開します：

var result = await _publisher.PublishAsync(          // DI から注入された DistributedDocumentPublisher
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // 現在使用しているのと同じフォルダー
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

読み取り側 — 任意のノードが共有領域から提供します：

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* 上記と同じ FileShareConfig */;
    }, "/"));

トポロジーは変更されません。 RootPath を同じ UNC 共有に設定すれば、すべてのノードは現在と同様に動作し続けます。変更点は、公開がレンダリングの副作用ではなく、呼び出す操作になることです。

両方の側が一致する必要があります。 RootPath または UsePerTokenSubfolders がパブリッシャーとハンドラで異なる場合、もう一方のノードは 404 を返します。設定を 1 つのヘルパーで構築し、両側から呼び出してください。

PageWaitTimeSeconds = 180 は「ページが表示されるまで最大 3 分ブロックする」ことを意味していました。置き換えは明示的です：FirstPagePriority = true を設定すると、ページ 1 はすぐに提供可能になり、以降のページは書き込みが完了するまで HTTP 202 Accepted を返します。バンドルされたビューアは retryOn409 が設定されている場合に自動的にリトライします。リトライしないクライアントは、まだレンダリング中のページのタイルが壊れた状態で表示されます。

バックグラウンドの公開やアクセスチケットを含む完全な構成は、分散デプロイ にあります。

8. 変換はプラグインで、はるかに小さい

プラグインを登録し、DocumentConverter ファサードを注入します：

builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());

// 以前の統合
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// 現在の統合
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

置き換えるもの：

• SourceFormatConverter — なし。ファイル拡張子を文字列で渡します（ドットを含む）。
• ファミリーごとの *ConfigConverter 型（WordConfigConverter、ExcelConfigConverter、…）は、入れ子の EnTargetFormat 列挙型を持ちますが、これらは廃止されました。現在は各ファミリーに対して 1 つの ConversionTarget 列挙型があります。
• viewer.Converter.GetConverter() — なし。Doconut.DocumentConverter を注入します。

ConvertAsync はシーク可能なストリームを返すため、return File(result, mime, name) を直接使用できます — 旧コードで必要だった MemoryStream のコピーは不要です。提供されているサンプルでは、68 ケースの拡張子スイッチとほぼ同一のコントローラが 10 個削除されました。

完全な機能一覧は コンバータプラグイン を参照してください。

9. クラウドプロバイダー

UseDoconutCloud がジェネリックになりました。プロバイダーはミドルウェア内部で Location 値に基づいて切り替える代わりに、型引数として指定します：

// 以前の統合
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// 現在の統合
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

設定クラスは名前空間（Doconut.Configs.Cloud → Doconut.Clouds）を除き変更されていません：AzureConfig、AmazonConfig、GoogleCloudConfig、DropBoxConfig、RedisConfig、CDNConfig、FTPConfig に加えて新しい FileShareConfig があります。ハンドラは <Provider>CloudHandler という名前です。

CDN ハンドラは 読み取り専用 です — 既に CDN にあるものを提供するだけで、アップロードは行いません。

10. 名前が変更された構成オブジェクト

DocOptions に IsSecured が追加されました。

現在の API は以前よりも関心事を厳密に分離しています。そのため、各設定が現在所有しているオブジェクトにあるか確認してください：

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

11. クライアント側ビューア — 静かに失敗する 2 つの変更

これらの変更はサーバー側の動作を完璧に保ちます。ドキュメントは正しくレンダリングされ、ページも正しく表示され、ブラウザのコンソールにも何も出力されません。C# が最初にコンパイルできても、このセクションは必ず読んでください。

ビューアのコールバックはオプションになり、グローバル関数ではなくなりました

以前のビューアはハンドラを 名前で 呼び出し、コンテナ ID からグローバル関数名を導出していました。<div id="div_ctlDoc"> があるページで function ctlDoc_OnViewerReady() を宣言するだけで十分でした。現在のビューアはオプションオブジェクトで明示的なコールバックを受け取り、これらのグローバル関数は探しません：

objctlDoc = $("#div_ctlDoc").docViewer({
    // ... 既存のオプション ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // 名前で見つかっていました
    onViewerReady:    ctlDoc_OnViewerReady,     // 名前で見つかっていました
    onCopy:           ctlDoc_Copy,              // ctlDoc_Copy(text) が呼び出されていました
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // ctlDoc_AutoLoadStatus(page) が呼び出されていました
});

なぜこれが問題か: 旧コードでは呼び出しが空の catch でラップされており、すべての例外が飲み込まれていました。現在は関数が実行されず、エラーも報告されません。一般的な症状は、停止しないビジー スピナーです — それは非表示にする関数 ctlDoc_OnViewerReady が呼び出されなかったためです。背後のドキュメント自体は問題ありません。

全オプション一覧は onPageLoading、onPageLoaded、onThumbnailClicked、onPageClicked、onDoubleClick、onViewerBusy、onViewerReady、onViewerError、onCopy、onAnnSaved、onAnnSaveError、onAnnLoaded、onAnnClosed、onAutoLoadStatus、onThumbsShown、onError です。リンククリックのコールバックはありません。ハイパーリンクの処理は組み込みで、showHyperlinks によって制御されます。

ResPath はリソースプレフィックスを指す必要があります

ResPath: '',                      // BEFORE — リソースはアプリケーションのルートから取得されていました
ResPath: 'doconut-res/images',    // NOW    — UseDoconutResources() がマウントするプレフィックス

DoconutOptions.ResourcesPath でプレフィックスを変更した場合は、その値を使用してください。

12. ビューアツールバー、検索、アノテーション

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

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

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

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

13. プラグイン登録

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

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

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

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

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

builder.Services.AddDistributedMemoryCache(); // セッション状態にはキャッシュが必要です（MVC/Razor Pages はすでに追加しています）
builder.Services.AddSession();
app.UseSession();

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

ファーム環境では、ページリクエストが最初のリクエストを受け取っていないノードに届くことがあり、その場合セッション単位のチェックで拒否されます。これが UnsafeMode = true が正当になる唯一のケースであり、AddDoconutDistributedDocumentSecurity を通じた署名付きアクセスチケットと組み合わせる必要があり、単独で使用すべきではありません。詳しくは 分散デプロイ を参照してください。

命名に関する注意

すべてのフレームワークでクラスは Viewer です。古いスニペットやサードパーティの記事で DocumentViewer を見つけても、その型は SDK には存在しません。

15. 推奨作業順序

1. ホストフレームワークが netstandard2.1 を利用できることを確認してください。利用できない場合は中止してください。
2. パッケージを 26.8.0 に更新し、ビルドしてください。コンパイルエラーを解消します—ほとんどは §1 の using 行です。
3. スタートアップを AddDoconut() に移し、ミドルウェア呼び出しを新しい順序（§3、§4）に変更してください。
4. Viewer を構築していた場所に注入し、OpenDocument を非同期にし、InitCache() を削除してください（§5、§6）。
5. Web ファームを使用している場合は §7 を実行してください—名前変更ではなく再設計が必要な唯一の部分です。
6. ドキュメントを変換する場合は §8 を実行してください。
7. §11 を実行してください — クライアント側の変更です。 これらは自動的に通知されません。
8. ブラウザで実際のドキュメントを開き、ビジースピナーを確認してください。 緑色のビルドは何も証明しません：ライセンス、プラグイン登録、リソースパス、ビューアコールバックはすべて実行時に失敗します。ファーム環境では、あるノードで公開されたドキュメントが別のノードで提供されていることを確認してください。

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

最低限、以下を確認してください：

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

ロールバック計画

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

切り替え前に、以下を文書化します：

• ロールバックに使用するデプロイメントスロットまたはアーティファクト；
• 共有ストレージへの影響（該当する場合）— 26.8.0 で公開されたアーティファクトは以前のウェブファームミドルウェアでは使用されません；
• アクティブなドキュメントセッションがどのように無効化されるか；
• ロールバック判断に使用するヘルスチェックとスモークドキュメント；
• 誰が以前のパッケージセットと構成を復元できるか。

旧ドキュメント

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

netstandard2.0 のインストールが残っている間は、ブックマークやサポートチケットに歴史的な URL を保持してください。これは別の世代を文書化しており、現在の API へはリダイレクトされません。