ビューアの動作方法

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

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

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

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

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

Inject it wherever you need it:

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

OpenDocumentAsync の内部で何が起こるか

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

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

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

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

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

• 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. を含むエラー画像が返されます。

ドキュメントのクローズ

viewer.CloseDocument(token);

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

まとめ

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