ビューアの動作概要
ドキュメント要求ライフサイクル
Doconut はドキュメントをページングされた画像として、ASP.NET Core ミドルウェアを通じて配信します。ライフサイクル(オープン、トークン、ページリクエスト、クローズ)を理解すれば、エラーメッセージを含むほぼすべての動作を説明できます。
3つの主要コンポーネント
Viewer— 注入する公開サービスです。ドキュメントを開き、セッショントークンを返します。- ドキュメントセッション — ロードされたドキュメントを保持するサーバー側オブジェクトで、
IMemoryCacheのトークンをキーにしています。 - Doconut ミドルウェア —
UseDoconut()によって追加され、ブラウザウィジェットが行うすべてのリクエスト(pages、thumbnails、search、annotations、…)に応答し、常にトークンで認証されます。
Viewer はステートレス — 設計上
Viewer はシールドされており、リクエストごとのドキュメント状態を保持せず、意図的に IDisposable を実装しません。セッションはセッションマネージャーで独立して管理され、キャッシュの期限切れまたは明示的な CloseDocument(token) によってクリーンアップされます。
必要な場所へ注入してください:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});OpenDocumentAsync の内部で何が起こるか
- ライセンスゲート — 拒否された、またはバージョン期限切れのライセンス(ブラックリスト登録、改ざん、またはライセンスの更新ウィンドウ外のビルド)は、即座に
LicenseExceptionをスローし、拒否理由をメッセージとして提供します — 無効なライセンス(欠如ではなく)に対しては、オープンは決して黙って劣化しません。カレンダー期限切れの一時的またはサブスクリプションライセンスは例外で、スローせずに透かしに劣化します。 - セッション作成 — ビューアファクトリはファイル拡張子に適したフォーマットビューアを選択し、ドキュメントをロードします(Rendering Pipeline を参照)。セッションは新しい GUID トークンで
IMemoryCacheに保存され、スライディング有効期限 —DocOptions.TimeOut分(デフォルトは 60 分)があります。各ページリクエストでタイマーがリセットされます。 - セキュリティ登録 — デフォルトの
UnsafeMode = falseを使用すると、トークンは呼び出し元の ASP.NET セッションに結び付けられます:セッションにsecure-{token}マーカーが書き込まれ、ドキュメントを開いたブラウザセッションだけがページをリクエストできます。 - トークンが返されます — それは以降のすべての操作に対する唯一の認証情報です。
これら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 技術メタデータ;.NET 6 の DICOM セッションに対して 501 を返します |
?token=…&action=rotate/flip/close | ページアクションと明示的なクローズ |
?token=…&AnnSave=… / &AnnLoad | 注釈の保存/読み込み |
これらのパスはすべて最初に検証されます:
- No token → トークンがない場合、ミドルウェアは 404 を返します(
ShowDoconutInfo = trueのときはバージョンバナーを返すこともあります)。 - Unknown or expired token →
Document session not found. Please re-open document.を含むエラー画像が返されます。 - Session middleware missing(
UnsafeMode = falseがある場合)→Session middleware not configured. Call UseSession() before UseDoconut().を伴う HTTP 500 が返されます。 - Token opened by a different browser session →
You Are Not Authorized To View This Page.を含むエラー画像が返されます。
ページを開くノードではなく共有ストレージから提供する場合は、全く別の構成になります;Distributed Deployments を参照してください。
ドキュメントのクローズ
viewer.CloseDocument(token);CloseDocument はキャッシュからセッションを削除します(これにより基盤となるドキュメントエンジンが破棄され、メモリが即座に解放されます)、secure-{token} マーカーを削除し、アクセス権を取り消します。呼び出しは任意です — スライディング有効期限が自動的に同じクリーンアップを行います — ただし大きなドキュメントの場合、ユーザーが完了した瞬間にメモリを解放する礼儀正しい方法です。
まとめ
- 1つのオープンドキュメント = 1つのセッション = 1つのトークン。トークンはブラウザセッションごとに付与され、グローバルな URL ではありません。
- トークンはスライディングウィンドウで期限切れになります;
DocOptions.TimeOutを過ぎてアイドル状態のビューアは再オープンが必要です。 Viewerは自由に注入・共有でき、セッションがすべての状態を保持します。
このページは役に立ちましたか?