レンダリングパイプライン

OpenDocumentAsync とブラウザに届く PNG の間には、2 つの明確な段階があります：viewer resolution（どのエンジンがドキュメントをロードするか、オープンごとに一度決定）とpage processing（各リクエストで各ページ画像に何が起こるか）。両方を理解することで、フォーマットがそのようにレンダリングされる理由と、DefaultRender が実際に何を切り替えるかが分かります。

ステージ 1 — フォーマットビューアの解決

ファクトリはファイル拡張子をフォーマットカタログを介してビューアにマッピングし、3 つの優先順位レベルがあります：

1. カスタムビューアが最優先。 DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) で登録したものは、すべての組み込みビューアよりも優先されます。
2. 組み込みファミリービューア。 カタログは各表示可能拡張子をビューアファミリ（Word、Excel、PowerPoint、Pdf、Cad、Dgn、Image、Tiff、Psd、Email、Visio、Project、Xps、Epub、Txt、Html、Mht、Dcn）にマッピングし、各ファミリは独自のエンジンアダプタを持ちます。同じ拡張子に対してライセンス済みプラグインがビューアを提供する場合、プラグインビューアが組み込みビューアを置き換えます。AddDoconut() は起動時に登録されたプラグインの権利を検証し、ファクトリの組み込みビューアへのフォールバックは防御的なランタイムルールです。
3. プラグイン専用フォーマット。 一部の拡張子には組み込みビューアが全くありません — DICOM（.dcm）は DICOM プラグインを通じてのみ利用可能です。必要な機能がない状態で開くと例外がスローされます：

LicenseException: This document type requires the 'Dicom' plugin license.

ビューアが存在しない拡張子は次の例外を発生させます：

FormatNotSupportedException: Document format '<extension>' is not supported.

解決後、設定は確定します：明示的に渡した設定オブジェクトがあればそれを使用し、なければカタログから取得したフォーマットのデフォルト設定を使用します。DocOptions.Password は保護されたドキュメント用に設定にコピーされます。

ステージ 1b — リダイレクトモード (DefaultRender = false)

ほとんどのフォーマット別設定は DefaultRender フラグを公開しています。これは根本的に異なる 2 つのパスのどちらかを選択します：

• DefaultRender = true — ドキュメントはネイティブにレンダリングされ、直接ページ画像になります。
• DefaultRender = false — ドキュメントは最初に メモリ内で PDF に変換 され、ソースエンジンは解放され、PDF ビューアが引き継ぎます。生成された PDF は実際のテキストを埋め込むため、全文検索はピクセル単位で正確なハイライトが得られます。パイプラインはリダイレクトされた PDF に対して AllowSearch と AllowCopy を有効にします（変換はユーザーに見えないため）。

XPS とカタログのデフォルトである MHT はリダイレクトパスを使用します。PDF 投影は HTML や Microsoft Project などのフォーマットに対してネイティブ検索を提供できます。生成された PDF にテキスト層がない画像が含まれる場合、標準ビューアはそれらのピクセルを検索できません。

テキストを含む PDF 投影が必要なときはリダイレクトモードを使用してください — ドキュメントが開かれる際に事前変換が発生するコストがあります。

ステージ 2 — ページイメージパイプライン

レンダリングされたページはリクエストごとに固定シーケンスで処理されます：

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• Watermark — ライセンス状態（ライセンス未取得、期限切れの一時またはサブスクリプション、無効なドメイン、バージョン不一致）と DocOptions.Watermark によるカスタムテキストから適用されます。適切にライセンスされたアプリ、または有効な一時ライセンスでカスタム透かしが設定されていない場合、このステップはスキップされます。
• Rotate/flip — ユーザーがウィジェットで設定したページ単位の状態（90°/180°/270°、水平/垂直フリップ）がセッションに保存され、以降のそのページのレンダリング時に適用されます。
• Scale — サムネイルとズームレベルは、要求されたターゲットサイズに合わせてレンダリングページをスケーリングして生成されます。0 は元サイズで提供することを意味します。
• Annotation burn — 保存されたアノテーションがビットマップ上に描画され、エクスポートやページ画像に反映されます。
• Encoding — 結果はプールされたメモリストリームを使用して PNG にエンコードされ、直接 HTTP 応答に書き込まれます。

ミドルウェア内部で発生したエラーは PNG エラー画像（白地に赤文字）として返され、HTTP エラーページではなくウィジェットがページ領域に表示できるようになります。

ページキャッシュ

BaseConfig.CachePages（デフォルト true）は、ドキュメントセッションの存続期間中、レンダリングされたページ画像をメモリに保持します。そのため、ページを再訪問しても再レンダリングされません。BaseConfig.ImageResolution（25–300 DPI、0 = フォーマットデフォルト）は品質/メモリの主要な調整項目で、各フォーマットのデフォルトはその設定ページに記載されています。

DocOptions.ImageResolution は 廃止予定 で、レンダリング品質を制御しません。以前のライブラリからアプリケーションを移行している場合は、その値をフォーマット設定に移動してください。コンパイラがすべての呼び出し箇所を指摘します。

単一ノードと多数ノードでのレンダリング

上記は、ドキュメントを開いたセッション向けにオンデマンドで単一ノードがレンダリングするケースを説明しています。1 つのノードが全アーティファクトセットをレンダリング・公開し、他のノードが共有ストレージからそれらのページを提供するデプロイメントは、別の読み取りパスを使用します — 詳細は 分散デプロイメント を参照してください。

何を調整すべきか