マイグレーション

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

このページでは、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 (old API, shown for contrast — not valid on .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 injected, license configured once in AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

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() が必須です。

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