移行

Doconut を .NET 8 にアップグレード

このページでは、2 つの移行が対象です：パッケージ バージョンのアップグレード（.NET 8 内）と、古い Doconut フレームワーク（.NET 6、.NET Standard 2.0、.NET Framework 4.7）から .NET 8 API への統合の移行です。

パッケージ バージョンのアップグレード

  1. パッケージを更新します（プラグイン パッケージも同様にバージョンを合わせてください）：
bash
dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom

  1. ライセンス ウィンドウを確認してください。 ライセンスはバージョン範囲をカバーします。新しいバージョンがその範囲外の場合、開くことは ブロック されます — OpenDocumentAsync は LicenseException をスローします（即座に失敗）。透かしにフォールバックせず、IsVersionValid は false になります。ライセンスを更新し、.lic を置き換えて、アプリケーションを再起動すると AddDoconut() が新しいライセンスを読み込みます。

  2. 再ビルドし、NuGet に宣言された依存バージョンを復元させます — System.Text.Json や System.Drawing.Common を再度固定しないでください（ダウングレードが引き起こす正確なエラーはトラブルシューティングをご参照）。

  3. 使用している各フォーマット ファミリーにつき、1 つのドキュメントでスモークテストを実施してください。

.NET 6 / .NET Standard 2.0 からの移行

.NET 8 API は DI と非同期を中心に再設計されています。対応表は以下の通りです：

項目.NET 6 / Standard 2.0.NET 8
セットアップConstruct Viewer(cache, httpContextAccessor, licensePath)builder.Services.AddDoconut(options => …) + inject Viewer
ライセンスStatic Viewer.DoconutLicense(path) + SetLicensePlugin(...) per pluginoptions.LicensePath / LicenseContent / LicenseStream — one license, auto-discovery for plugin files
オープンviewer.OpenDocument(...) (synchronous)await viewer.OpenDocumentAsync(...)
クローズviewer.CloseDocument() or viewer.Dispose()viewer.CloseDocument(token) — Viewer is not IDisposable
ライフタイムViewer implements IDisposable, holds the open documentViewer is stateless; sessions live in the cache under tokens
コンバータviewer.Converter propertyThe Converter plugin (AddPlugin<ConverterPlugin>()) + the DocumentConverter service
設定クラスDoconut.Configs.View.* namespacesAll in the Doconut namespace
ミドルウェアManual handler wiringapp.UseDoconutResources() + app.UseDoconut()

典型的なビフォー/アフターは次の通りです：

text
// .NET 6（古い API、対比のために示しています — .NET 8 では有効ではありません）
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.Viewer.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());
csharp
// .NET 8 — Viewer が注入され、ライセンスは AddDoconut() で一度だけ設定されます
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

.NET Framework 4.7（Web Forms）からの移行

.NET Framework 4.7 の Viewer は WebControl です；.NET 8 はコントロールモデルをミドルウェア + DI サービスに置き換えます：

  • <doconut:DocViewer runat=server> コントロールはなくなります — ページはウィジェットの div ペアをホストし、エンドポイントがトークンを返します（クイックスタートにパターンがあります）。
  • 静的ライセンス メソッド → DoconutOptions のライセンス ソース。
  • 同期 OpenDocument → await OpenDocumentAsync。
  • Viewer.ReferenceScripts() / ReferenceCss() は両方の環境で存在します — .NET 8 バージョンは ScriptConfig/CssConfig オブジェクトを受け取り、ライセンスで制御されます。
  • コントロール プロパティ（ShowThumbs、PageZoom、FixedZoom、…） → ViewerConfig や docViewer の JS オプションでも同名で使用します。
  • byte[] を返すエクスポート メソッド → Viewer の非同期アノテーション エクスポート API に置き換えます。

この移行は、変更されていない概念（open → token → widget）を中心にホスティング層をリライトする形で計画してください。

名前に関する注意

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

移行チェックリスト

  1. パッケージを入れ替え、プラグイン パッケージのバージョンを合わせます。
  2. ライセンス設定を AddDoconut() に移動し、静的ライセンス呼び出しを削除します。
  3. オープン呼び出しを非同期にし、Dispose や引数なしの CloseDocument を CloseDocument(token) に置き換えます。
  4. viewer.Converter の使用を、コンバータ プラグインの登録と DocumentConverter に置き換えます。
  5. セキュリティ パスを再テストしてください：デフォルトのセキュリティでは AddSession()/UseSession() が必須になり（ミニマル API アプリでは AddDistributedMemoryCache() も追加します）。

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