ビューアの仕組み
ドキュメント要求ライフサイクル
Doconut はドキュメントをページ化された画像として ASP.NET Core ミドルウェアを通じて配信します。ライフサイクル(オープン、トークン、ページリクエスト、クローズ)を理解することで、エラーメッセージを含むほぼすべての挙動を説明できます。
3つの主要コンポーネント
Viewer— 注入する公開サービスです。ドキュメントを開き、セッショントークンを返します。- ドキュメントセッション — ロードされたドキュメントを保持するサーバー側オブジェクトで、
IMemoryCacheのトークンをキーにします。 - Doconut ミドルウェア —
UseDoconut()によって追加され、ブラウザウィジェットが行うすべてのリクエスト(pages、thumbnails、search、annotations、…)に応答し、常にトークンで認証されます。
Viewer はステートレス — 設計上
Viewer はシールドされており、リクエストごとのドキュメント状態を保持せず、意図的に IDisposable を実装しません。セッションはセッションマネージャーで独立して管理され、キャッシュの期限切れまたは明示的な CloseDocument(token) によってクリーンアップされます。
もはや自分で構築する必要はありません。AddDoconut() はそれをトランジェントサービスとして登録します。必要な場所へ注入してください:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});MVC アプリケーションではコンストラクタパラメータとして取得し、Razor ビューでは @inject Doconut.Viewer Viewer を使用します。Viewer インスタンスのアプリケーション所有キャッシュはもはや必要なく、また正しくもありません。なぜならキャッシュに値するものを保持していないからです。
OpenDocumentAsync の内部で何が起こるか
- ライセンスゲート。 拒否された、またはバージョン期限切れのライセンス(ブラックリスト登録、改ざん、またはライセンス更新ウィンドウ外のビルド)は、即座に
LicenseExceptionをスローし、拒否理由をメッセージとして提供します — 無効な(欠如しているのとは異なる)ライセンスに対しては、オープン時に黙って劣化しません。カレンダー期限切れの一時またはサブスクリプションライセンスは例外で、スローせずに透かしに劣化します。 - セッション作成。 ビューワーファクトリはファイル拡張子に適したフォーマットビューワーを選択し、ドキュメントをロードします(レンダリング パイプライン を参照)。セッションは新しい GUID トークンとともに
IMemoryCacheに保存され、スライディング有効期限 —DocOptions.TimeOut分(デフォルト 60)で管理されます。各ページリクエストで時計がリセットされます。 - セキュリティ登録。 デフォルトの
UnsafeMode = falseを使用すると、トークンは呼び出し元の ASP.NET セッションにバインドされます:secure-{token}マーカーがセッションに書き込まれ、ドキュメントを開いたブラウザセッションだけがページをリクエストできるようになります。 - トークンが返されます。 それは以降のすべての操作に対する唯一の認証情報です。
別個のウォームアップステップはありません。以前のライブラリはその目的で InitCache() を提供していましたが、現在は存在せず、代替もありません。
3つのオーバーロードは入力が異なるだけです:ファイルパス、ファイルパスにフォーマット別設定(PdfConfig、WordConfig、…)を加えたもの、または拡張子でフォーマット検出を行う Stream と FileInfo の組み合わせです。
ウィジェットがページを取得する方法
クライアントウィジェットはクエリ文字列にトークンを付けて Doconut ミドルウェアを呼び出します。ミドルウェアの動作はリクエスト内容に依存します:
| クエリ | 用途 |
|---|---|
?token=…&page=N | レンダリングされたページ画像(PNG) |
?token=…&page=N&thumb=1 | サムネイル |
?token=…&zoom=… | 拡大ページレンダリング |
?token=…&search=term | 全文検索(ライセンス制御) |
?token=…&bookmarks | ドキュメントのアウトライン/ブックマーク |
?token=…© / &showlinks / &fileFormat | テキストコピー、ハイパーリンク、フォーマット情報 |
?token=…&meta | DICOM 技術メタデータ;このパッケージの DICOM セッション用に 501 を返します |
?token=…&action=rotate/flip/close | ページアクションと明示的なクローズ |
?token=…&AnnSave=… / &AnnLoad | アノテーションの保存/読み込み |
これらのパスはすべて最初に検証されます:
- トークンなし → トークンが無い場合、ミドルウェアは 404 を返します(
ShowDoconutInfo = trueのときはバージョンバナーを返すことも)。 - 不明または期限切れトークン →
Document session not found. Please re-open document.を含むエラー画像が返されます。 - セッションミドルウェアが欠如(
UnsafeMode = falseがある場合)→Session middleware not configured. Call UseSession() before UseDoconut().を含む HTTP 500 が返されます。 - 別のブラウザセッションで開かれたトークン →
You Are Not Authorized To View This Page.を含むエラー画像が返されます。
ミドルウェアのマウント場所
UseDoconut() はトークンを含むリクエストに応答します。マウント場所はどこでも構いません。一般的な設定では、DocImage.axd のリクエスト形状を MapWhen ブランチ上に保持し、既存のクライアントが常に同じ URL を呼び出し続けられるようにします。選択する方法に関わらず、クライアントの BasePath はそれと一致している必要があります — ビューア設定 を参照してください。
ページを開くノードではなく共有ストレージから提供する場合は、全く別の構成になります — 分散デプロイ を参照してください。
ドキュメントのクローズ
viewer.CloseDocument(token);CloseDocument はキャッシュからセッションを削除します(これにより基盤となるドキュメントエンジンが破棄され、メモリが即座に解放されます)、secure-{token} マーカーを削除し、アクセス権を取り消します。呼び出しは任意です — スライディング有効期限が同様のクリーンアップを自動的に行います — が、大きなドキュメントの場合、ユーザーが終了した瞬間にメモリを解放する礼儀正しい方法です。
これは注入された Viewer 上で呼び出されます。以前のパターン — トークンを閉じるだけの目的で using ブロック内に短命な Viewer を構築する — は同等のものがなく、必要ありません。
まとめ
- 1つのオープンドキュメント = 1つのセッション = 1つのトークン。トークンはブラウザセッションごとに割り当てられ、グローバルな URL ではありません。
- トークンはスライディングウィンドウで期限切れになります。
DocOptions.TimeOutを過ぎてアイドル状態のビューワーは再オープンが必要です。 Viewerは注入して自由に共有できます。セッションがすべての状態を保持します。
このページは役に立ちましたか?