Wie der Viewer funktioniert

Doconut rendert Dokumente als paginierte Bilder, die über ASP.NET Core Middleware bereitgestellt werden. Das Verständnis des Lebenszyklus — Öffnen, Token, Seitenanfragen, Schließen — erklärt fast jedes Verhalten, das Sie beobachten werden, einschließlich der Fehlermeldungen.

Die drei beweglichen Teile

• Viewer — der öffentliche Dienst, den Sie injizieren. Er öffnet Dokumente und gibt Sitzungs‑Token zurück.
• Die Dokumentensitzung — ein serverseitiges Objekt, das das geladene Dokument hält und über einen Token in IMemoryCache adressiert wird.
• Die Doconut-Middleware — hinzugefügt durch UseDoconut(); beantwortet jede Anfrage, die das Browser-Widget stellt (pages, thumbnails, search, annotations, …), stets authentifiziert durch den Token.

Viewer ist zustandslos — per Design

Viewer ist versiegelt, hält keinen pro‑Anfrage‑Dokumentzustand und implementiert bewusst nicht IDisposable. Sitzungen existieren unabhängig im Sitzungsmanager und werden durch Cache‑Ablauf oder ein explizites CloseDocument(token) bereinigt.

Injizieren Sie es dort, wo Sie es benötigen:

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

Was passiert innerhalb von OpenDocumentAsync

1. Lizenzprüfung. Eine abgelehnte oder versionsabgelaufene Lizenz (auf der schwarzen Liste, manipuliert oder ein Build außerhalb des Aktualisierungsfensters der Lizenz) wirft sofort eine LicenseException mit dem Ablehnungsgrund als Nachricht — das Öffnen degradert niemals stillschweigend bei einer ungültigen (im Gegensatz zu fehlenden) Lizenz. Eine kalenderabgelaufene temporäre oder Abonnement‑Lizenz ist die Ausnahme: Sie wirft nicht — sie degradert zu einem Wasserzeichen.
2. Sitzungserstellung. Die Viewer‑Factory wählt den richtigen Format‑Viewer für die Dateierweiterung und lädt das Dokument (siehe Rendering‑Pipeline). Die Sitzung wird in IMemoryCache unter einem frischen GUID‑Token mit einer gleitenden Ablaufzeit — DocOptions.TimeOut Minuten, standardmäßig 60 — gespeichert. Jede Seitenanfrage setzt die Uhr zurück.
3. Sicherheitsregistrierung. Bei UnsafeMode = false (Standard) ist der Token an die ASP.NET‑Sitzung des Aufrufers gebunden: ein secure-{token}‑Marker wird in die Sitzung geschrieben, sodass nur die Browsersitzung, die das Dokument geöffnet hat, dessen Seiten anfordern kann.
4. Der Token wird zurückgegeben. Er ist das einzige Anmeldecredential für alles, was folgt.

Die drei Überladungen unterscheiden sich nur im Eingabeparameter: ein Dateipfad, ein Dateipfad plus eine formatbezogene Konfiguration (PdfConfig, WordConfig, …) oder ein Stream plus ein FileInfo, dessen Erweiterung die Format­erkennung steuert.

Wie das Widget Seiten erhält

Das Client‑Widget ruft die Doconut‑Middleware mit dem Token in der Abfragezeichenfolge auf. Was die Middleware tut, hängt von der Anfrage ab:

Jeder dieser Pfade prüft zuerst:

• Kein Token → die Middleware gibt 404 zurück (oder ein Versionsbanner, wenn ShowDoconutInfo = true).
• Unbekannter oder abgelaufener Token → ein Fehlbild mit Document session not found. Please re-open document.
• Sitzungs‑Middleware fehlt (bei UnsafeMode = false) → HTTP 500 mit Session middleware not configured. Call UseSession() before UseDoconut().
• Token von einer anderen Browsersitzung geöffnet → ein Fehlbild mit You Are Not Authorized To View This Page.

Schließen eines Dokuments

viewer.CloseDocument(token);

CloseDocument entfernt die Sitzung aus dem Cache (der die zugrunde liegende Dokumenten‑Engine entsorgt und deren Speicher sofort freigibt), löscht den secure-{token}‑Marker und widerruft die Zugriffsberechtigung. Der Aufruf ist optional — die gleitende Ablaufzeit führt dieselbe Bereinigung automatisch durch — aber bei großen Dokumenten ist es die höfliche Art, den Speicher sofort freizugeben, sobald der Benutzer fertig ist.

Fazit

• Ein geöffnetes Dokument = eine Sitzung = ein Token. Tokens gelten pro Browsersitzung, nicht als globale URLs.
• Der Token läuft in einem gleitenden Fenster ab; ein Viewer, der länger als DocOptions.TimeOut untätig bleibt, muss das Dokument erneut öffnen.
• Viewer kann frei injiziert und geteilt werden; Sitzungen enthalten den gesamten Zustand.