ビューアの動作概要

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

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

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

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

Viewer は sealed で、リクエストごとのドキュメント状態を保持せず、意図的に 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 の内部で起こること

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

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

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

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

これらのパスはすべて最初に検証されます。

• トークンがない場合 → ミドルウェアは 404 を返します（ShowDoconutInfo = true のときはバージョンバナーを表示）。
• トークンが不明または期限切れの場合 → エラー画像が返され、メッセージは「ドキュメントセッションが見つかりません。ドキュメントを再度開いてください。」
• セッションミドルウェアが構成されていない場合（UnsafeMode = false） → HTTP 500 が返され、メッセージは「セッションミドルウェアが構成されていません。UseDoconut() の前に UseSession() を呼び出してください。」
• 別のブラウザセッションで開かれたトークンの場合 → エラー画像が返され、メッセージは「このページを表示する権限がありません。」

ドキュメントのクローズ

viewer.CloseDocument(token);

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

まとめ

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