マイグレーション

このページでは、既存の ASP.NET アプリケーションを Doconut.NETFramework 26.8.0 以前 (.NET Framework 4.7) から 26.9.0 以降 (.NET Framework 4.7.2) にアップグレードする方法を説明します。Doconut のサンプルパッケージには完全な移行ガイドと、新しい API に移植された従来のサンプル（MVC 5、ウェブファーム、Web Forms）が含まれています。サンプルと自分のアプリケーションを比較することが最も速い方法です。

1 つのパッケージ、2 つのバージョン

両方のライブラリは同じパッケージ ID Doconut.NETFramework で公開されています。バージョンで区別されます：

パッケージを更新することがアップグレードです。別個のインストール用パッケージや互換性レイヤーはありません：26.9.0 は異なる API 表面を持つため、更新後にはコンパイルエラーが発生することが予想されます（このページの残りで説明します）。.NET Framework 4.7 系は廃止され、26.8.0 が最後のリリースです。継続して使用することは可能ですが（ここにあるセキュリティ修正はありません）、新しいリリース、プラグイン、分散モード、ドロップインウィジェットは 26.9.0 以降でのみ提供されます。

1. ターゲットの変更とパッケージの更新

まず Web プロジェクトのターゲットを .NET Framework 4.7.2 に変更してください。4.7 を対象としたままでは 26.9.0 をインストールできず、NuGet が更新を拒否します。その後 Doconut.NETFramework を更新し、使用しているプラグインパッケージ（Doconut.NETFramework.Converter、Doconut.NETFramework.Dicom、…）を追加します。各プラグインにはそれを許可するライセンスが必要です。

プロジェクトが packages.config を使用している場合、更新時に前バージョンのアンインストール手順が実行され、Web.config から DocImage ハンドラが削除されますが、26.9.0 は再度追加しません。手順 3 に示すように再登録してください。再登録するまで、DocImage.axd は 404 を返し、ページは描画されません。

2. 名前空間: ほぼすべてがルートに移動

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

3. スタートアップ: DoconutHost.Initialize と 2 つの Web.config エントリ

従来のパッケージはリクエストごとにビューアを構築し、オプションはそのインスタンスのプロパティとして保持していました。新しいパッケージは Application_Start で一度だけ構築されるコンポジションルートを持ち、ビューアは解決するサービスになります：

// 以前 - Doconut.NETFramework 26.8.0 以前、リクエストに応じて
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0+ - ビューアは DoconutHost から解決され、ライセンスは DoconutHost.Initialize() で一度だけ設定されます
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize は Application_Start に、DoconutHost.Shutdown は Application_End に配置し、Web.config は DocImage.axd ハンドラとリソースモジュールを取得します — これらはすべて インストール にあります。ページ単位の外観設定（FitType、FixedZoom、ShowHyperlinks、…）はビューアインスタンスからウィジェットのオプション、または Viewer.RenderViewer に渡す ViewerConfig に移動しました（ViewerConfig を参照）。new Viewer() は DoconutHost.Initialize が実行された後もコンパイルされ続けるため、設定を移行しながらコードビハインドのその行を保持できます。

セキュリティは従来通りに機能します。 ドキュメントを開くと、現在の ASP.NET セッションにページへのアクセス権が付与され、DocImage.axd はそれ以外のすべてを拒否します。この機能をオフにした DoconutUnSafeMode アプリ設定は現在 DoconutHost.Initialize の options.UnsafeMode にあります — そのまま false にしておいてください。セッションとセキュリティ を参照してください。

サイト全体を停止させるスタートアップ失敗。 ライセンスが付与されていない機能を持つ登録済みプラグインが Application_Start で例外をスローし、アプリケーションはすべてのリクエストに対して空の 500 を返します — エラーページは表示されず、IIS ログにも何も記録されず、Windows イベントログ（ソース ASP.NET）にエントリが残るだけです。ライセンスはサイトルート下の wwwroot からのみ読み取られ、他の場所からは読み取られません。また、基本的な Doconut.Viewer.lic が存在しなければ、隣接するプラグインのライセンスも読み取られません。ライセンス設定 を参照してください。

4. Web farm: フラグから分散モードへ

従来のモデルは viewer.IsWebfarm = true と ExportToPng(path) でした。新しいモデルは一度だけ登録され、すべてのノードが1つのストアと1つの署名キーを共有し、ブラウザーに結び付けられた署名済みチケットが「どのノードが応答しても」の代わりになります：

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath はエイリアスです
        d.SigningKey        = farmKey;                           // >= 32 バイト、各ノードで同じ
    }));

その後、通常通りドキュメントを開き、ブラウザーを (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) にバインドし、トークンと共にウィジェットへ viewer.AccessToken を渡します。セッションとセキュリティ に手順があります；web-farm のサンプルは完全なノードです。IsWebfarm と WebfarmPath はまだコンパイルできますが、もはや何も切り替えません。

成功のように見えて実際はそうでないものが2つあります：DistributedDocumentPublisher.PublishAsync はドキュメントのレンダリングされたファイルを書き込みますがセッションを開きません。そのため、公開されたトークンを指すビューアはステータス200の約2KBエラー画像を取得します。また、doconut-client クッキーがないテストクライアントも同じ画像を取得し、401 にはなりません。サイズで実際のページとエラー画像を区別してください。

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

SourceFormatConverter 列挙型、12 の *ConfigConverter クラス、およびそれらの入れ子になったターゲット列挙型は、1つの列挙型 ConversionTarget と 1つの呼び出しに置き換えられます：

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// DoconutHost がすでに初期化されており、ct という名前の CancellationToken が利用可能であると仮定してください。
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* 入力ストリーム */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

ソース形式は渡した拡張子から取得されます。互換性のシムはありません：すべての SourceFormatConverter 参照はコンパイルエラーとなり、削除することで解決します。フォーマットごとのオプションオブジェクトは残らず、WordConfigConverter.HtmlOptions と CadConfigConverter.CadOptions.ShowColor は ConvertAsync では同等のものがありません。Web Forms では ConvertAsync でブロックしないでください — コンバータプラグイン を参照してください。

6. クラウドストレージ: 共有フォルダーとしてアクセス

クラウド構成タイプは Doconut.Clouds に変更なしで移行しました。ただし、クラウドリクエストハンドラは ASP.NET Core コンポーネントであり、従来のアプリケーションにはそれらを実行するパイプラインがありません。System.Web サイトからは、共有フォルダー としてクラウドストレージにアクセスします — Azure では、各ノードにマウントされた Azure Files 共有です — FileShareConfig を介してアドレス指定されます。

7. クライアント側の変更でサイレントに失敗するもの

以下の各項目はコンパイルされ、実行され、ログは出力されず、誤った動作をします：

さらに3つあります：ビューアは独自のツールバーを描画しません（ページが Zoom、Next、GotoPage とその他を自分のボタンに接続します）；非表示の Bootstrap モーダル内で作成されたビューアはサイズが0×0となり、コンテナに明示的な高さを与えて shown.bs.modal で再調整するまで何も描画しません；そして AllowSearch は PDF 用に false をデフォルトとするため、ドキュメントは完璧にレンダリングされますが、すべての検索は何も返しません。

8. 消えるもの

推奨作業順序

1. ターゲットを変更し、パッケージを入れ替えて、Global.asax を DoconutHost.Initialize と 2 つの Web.config 登録と共にコンパイルできるようにします。サイトが起動するはずです。
2. ビューアページを1つ作成：ドキュメントをレンダリングさせ、セクション7を通してツールバー、検索、アノテーションが機能するまで作業します。実際のブラウザで確認 — そのセクションでエラーが発生することはありません。
3. 変換（セクション5）：機械的で、コンパイルエラーの大半です。
4. 残りのページは、移植されたサンプルを差分対象として使用します。
5. ウェブファーム（セクション4）がある場合はそれを使用します。2つのノードとブラウザ、またはクッキーを保持するクライアントでテストしてください。