ビューアの仕組み

ドキュメント要求ライフサイクル

Doconut はドキュメントをページ化された画像として ASP.NET Core ミドルウェアを通じて提供します。ライフサイクル(オープン、トークン、ページリクエスト、クローズ)を理解すれば、エラーメッセージを含むほぼすべての挙動を説明できます。

3つの主要コンポーネント

  • Viewer — 注入する公開サービスです。ドキュメントを開き、セッショントークンを返します。
  • ドキュメントセッション — ロードされたドキュメントを保持し、IMemoryCache のトークンでキー付けされたサーバー側オブジェクトです。
  • Doconut ミドルウェア — UseDoconut() によって追加され、ブラウザウィジェットが行うすべてのリクエスト(pages、thumbnails、search、annotations、…)に応答し、常にトークンで認証されます。

Viewer はステートレスです — 設計上

Viewer はシールドされており、リクエストごとのドキュメント状態を保持せず、意図的に IDisposable を実装しません。セッションはセッションマネージャーで独立して管理され、キャッシュの期限切れまたは明示的な CloseDocument(token) によってクリーンアップされます。

必要な場所へ注入してください:

csharp
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

OpenDocumentAsync の内部で何が起こるか

  1. ライセンスゲート 拒否された、またはバージョン期限切れのライセンス(ブラックリスト登録、改ざん、またはライセンスの更新ウィンドウ外のビルド)は、即座に LicenseException をスローし、拒否理由をメッセージとして提供します — 無効な(欠如しているのとは対照的に)ライセンスの場合、オープンは決して黙って劣化しません。カレンダー期限切れの一時的またはサブスクリプションライセンスは例外で、スローせずに透かしに劣化します。
  2. セッション作成 ビューアファクトリはファイル拡張子に適したフォーマットビューアを選択し、ドキュメントをロードします(Rendering Pipeline 参照)。セッションは新しい GUID トークンで IMemoryCache に保存され、スライディング有効期限 — DocOptions.TimeOut 分(デフォルト 60)を持ちます。各ページリクエストで時計がリセットされます。
  3. セキュリティ登録 デフォルトの UnsafeMode = false を使用すると、トークンは呼び出し元の ASP.NET セッションにバインドされます:セッションに secure-{token} マーカーが書き込まれ、ドキュメントを開いたブラウザセッションだけがページをリクエストできるようになります。
  4. トークンが返されます それは以降のすべてに対する唯一の認証情報です。

3つのオーバーロードは入力が異なるだけです:ファイルパス、ファイルパスとフォーマット別設定(PdfConfig、WordConfig、…)の組み合わせ、または拡張子でフォーマット検出を行う Stream と FileInfo の組み合わせです。

ウィジェットがページを取得する方法

クライアントウィジェットはクエリ文字列にトークンを付けて Doconut ミドルウェアを呼び出します。ミドルウェアの動作はリクエストに依存します:

クエリ目的
?token=…&page=Nレンダリングされたページ画像(PNG)
?token=…&page=N&thumb=1サムネイル
?token=…&zoom=…ズームページレンダリング
?token=…&search=termフルテキスト検索(ライセンス制御)
?token=…&bookmarksドキュメントアウトライン/ブックマーク
?token=…&copy / &showlinks / &fileFormat / &metaテキストコピー、ハイパーリンク、フォーマット情報、DICOM 技術メタデータ
?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. を含むエラー画像が返されます。

ページを開くノードではなく共有ストレージから提供するのは全く別の構成です;分散デプロイメント を参照してください。

ドキュメントのクローズ

csharp
viewer.CloseDocument(token);

CloseDocument はキャッシュからセッションを削除し(基盤となるドキュメントエンジンを破棄し、メモリを即座に解放)、secure-{token} マーカーを削除し、アクセス権を取り消します。呼び出しは任意です — スライディング有効期限が自動的に同じクリーンアップを行います — が、大きなドキュメントの場合、ユーザーが終了した瞬間にメモリを解放する礼儀正しい方法です。

まとめ

  • 1つのオープンドキュメント = 1つのセッション = 1つのトークン。トークンはブラウザセッションごとに発行され、グローバルURLではありません。
  • トークンはスライディングウィンドウで期限切れになります;DocOptions.TimeOut を過ぎてアイドル状態のビューアは再オープンが必要です。
  • Viewer は自由に注入・共有でき、セッションがすべての状態を保持します。

このページは役に立ちましたか?