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

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

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

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

ページキャッシュ

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

調整項目の場所