Doconut ビューア は、PDF、Office、CAD、画像など、サポートされているさまざまなドキュメントファミリーをアプリケーション内に配置できる .NET ドキュメント表示ライブラリです。堅実な Doconut 統合は、最短のコードスニペットを探すことよりも、アプリケーション、ビューア、ブラウザ間の明確な境界を選択することに重点があります。
Doconut ドキュメンテーションハブ は、サポートされている .NET プロジェクトタイプ向けの公式セットアップパスへのリンクを提供しています。アプリケーションにインストールされているバージョンに合ったガイドを使用し、周辺ページ、ID チェック、アクセスワークフローを自チームが所有するアプリケーションコードとして扱ってください。
統合境界から始める
製品にドキュメントプレビューを配置する一般的な方法は 3 つあります。適切な選択は、ナビゲーション、認証、ビューアのライフサイクルを誰が所有するかに依存します。
| パターン | 最適な適用先 | 主なトレードオフ |
|---|---|---|
| アプリケーションビュー | 製品コントロールの横にビューアを表示する .NET ページ | 緊密な統合が可能だが、ページとビューアのライフサイクルが結合される |
| アプリケーション所有 iframe | ホスト UI とプレビュー経路の分離が必要なポータル | 境界が明確になるが、通信は明示的に設計する必要がある |
| サーバー経路を囲むフレームワークコンポーネント | .NET アプリケーションでバックエンドされた React、Angular、Vue シェル | フロントエンドの構成に慣れ親しんだ手法だが、管理すべきライフサイクル状態が増える |
iframe パターンは公開ドキュメント URL を指す必要はありません。自アプリケーション内の認証済みルートを指すことができ、そのルートでアクセスを検証し、ストレージパスをホストページに公開せずにビューアページをレンダリングできます。
安定かつレスポンシブなプレビュー領域を構築する
ブログの例示的なスニペットからビューアのマークアップや初期化を再構築しないでください。Doconut は各サポート対象 .NET ラインに適したファイル、ミドルウェア手順、名前空間、ビューア設定を公開しています。たとえば、公式の .NET 6 以上のセットアップガイド では、サーバーミドルウェア、ビューアオブジェクト、ドキュメントオプション、レンダリング設定、必要なクライアント資産が説明されています。
これらのバージョン管理された資料を使用してビューアを作成し、ホスト領域に安定した幅と高さを割り当ててください。ロード前に十分なスペースを確保し、周辺ページがジャンプしないようにし、製品がサポートする実際のブレークポイントでツールバーと最初のページをテストします。
構成に取り掛かる前に、公式の Doconut ライブデモ と比較してください。デモは複数の .NET およびフロントエンド統合スタイルをカバーしており、専用の iframe 例も含まれ、公式にサポートされたパスと見た目だけのスニペットを区別するのに役立ちます。
アクセス判断はサーバー側で行う
ホストページがユーザーの閲覧可否を決定してはいけません。プレビュー経路をレンダリングする前に、アプリケーションは次の手順を実行すべきです。
- リクエストを認証する。
- ユーザーが要求されたドキュメントおよびテナントに対して権限を持つか確認する。
- サーバー管理の識別子を通じてドキュメントを解決する。
- それらのチェックが通った後にのみビューアで開く。
- ストレージの詳細を漏らさないよう、見つからないまたは禁止された状態を汎用的に返す。
不透明な識別子は URL の衛生性を向上させますが、認可そのものではありません。ページ、サムネイル、検索、注釈、エクスポート、印刷リクエストにも同様のチェックを適用してください。
ホストとビューアの通信方法を決定する
アプリケーションビューは自コンポーネントを直接呼び出せますが、iframe にはより狭い契約が必要です。ホストが本当に必要とするイベントだけを定義しましょう。例:
- プレビュー準備完了
- ドキュメントのオープン失敗
- 現在ページの変更
- セッション期限切れ
- ユーザーがプレビューを閉じる要求
postMessage を使用する場合は、event.origin とメッセージ構造の両方を検証してください。本番環境でワイルドカードオリジンを受け入れず、認証情報、ストレージ位置、または生のドキュメント内容をメッセージで渡さないようにします。
ブラウザ制限を深層防御として扱う
iframe が自動的に分離されるわけではありません。sandbox 属性で機能を制限できますが、過度に厳しい設定はビューアスクリプト、ダウンロード、同一オリジン動作を壊す可能性があります。統合に記載された最小限の機能セットから開始し、Content Security Policy と併せてテストしてください。
さらに確認すべき項目:
- プレビュー経路の
frame-ancestorsまたはX-Frame-Options - ホストページの
frame-src - iframe がセッションを必要とする場合の Same-site クッキーの挙動
- ルーティング識別子を含む URL の Referrer ポリシー
- 機密情報を表示するページのキャッシュヘッダー
これらのコントロールは周辺アプリケーションとインフラストラクチャの責任です。ビューアコンポーネントがテナンシーや脅威モデルに合わせた正しいポリシーを選択することはできません。
ローディング、エラー、期限切れ状態の設計
空白の矩形は有用なエラーメッセージになりません。認可失敗、未対応入力、破損ファイル、タイムアウト、期限切れセッションなどの明示的な状態をホストページに提供し、内部パスや例外詳細を漏らさずに実行可能な表現にしてください。
長文ドキュメントの場合、最初のページが準備できるまでビューアコンテナを保持します。ユーザーがページ遷移せずにドキュメントを切り替えられる場合は、古いリクエストをキャンセルし、次のアイテムをロードする前に表示タイトル、ページ数、フォーカスをリセットします。
アクセシビリティとキーボード操作
すべての iframe に有用な title を付与してください。キーボードでプレビューにアクセスできるようにし、ホストページへフォーカスを戻す可視手段を提供し、カスタムオーバーレイ内にフォーカスが閉じ込められないようにします。ビューアが独自のキーボードショートカットを持つ場合は、製品シェルで使用されているショートカットとの競合を文書化してください。
アクセシブルなフォールバックとして、ビジネスルールで許可される場合に制御されたダウンロードや代替表現を提供できますが、単なるフォールバックとして公開ファイルリンクを追加しないでください。
実践的な検証チェックリスト
リリース前に、初回ページロードだけでなく完全なリクエストパスを検証してください。
- 認可されたユーザーが許可されたドキュメントを開けること。
- 別テナントのユーザーがプレビュー URL を再利用できないこと。
- ビューア関連エンドポイントへの直接リクエストでも同じ認可チェックが行われること。
- リフレッシュ、バックナビゲーション、セッション期限切れが理解可能な状態を生成すること。
- サポートされるビューポートサイズとズームレベルでプレビューが利用可能であること。
- ブラウザコンソールエラーや失敗したネットワークリクエストが監視で可視化されること。
- ストレージおよびアプリケーションログにシークレットや完全なドキュメント URL が記録されていないこと。
結論
最も保守性の高い Doconut 埋め込みは、契約が小さく明示的であるものです。バージョン化された公式ドキュメントで定義されたドキュメント表示の役割は Doconut に任せ、アイデンティティ、認可、ルーティング、保持、ブラウザポリシー、ユーザーフィードバックはアプリケーション側が所有してください。ローカルでパッケージ化されたサンプルを評価する準備ができたら、Doconut ダウンロードリソース を公式から取得し、無関係な記事からソースをコピーしないようにしましょう。