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, indiziert durch ein Token im IMemoryCache.
• Die Doconut‑Middleware — hinzugefügt durch UseDoconut(); beantwortet jede Anfrage, die das Browser‑Widget stellt (pages, thumbnails, search, annotations, …), immer authentifiziert durch das Token.

Viewer ist zustandslos — per Design

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

Sie konstruieren es nicht mehr. AddDoconut() registriert es als transienten Dienst; 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");
});

In einer MVC‑Anwendung nehmen Sie es als Konstruktorparameter; in einer Razor‑Ansicht verwenden Sie @inject Doconut.Viewer Viewer. Anwendungs‑eigene Caches von Viewer‑Instanzen werden nicht mehr benötigt — und sind nicht mehr korrekt, weil sie nichts zum Cachen enthalten.

Was passiert innerhalb von OpenDocumentAsync

1. Lizenzprüfung. Eine abgelehnte oder versionserlassene Lizenz (auf der schwarzen Liste, manipuliert oder ein Build außerhalb des Lizenz‑Update‑Fensters) wirft sofort eine LicenseException mit dem Ablehnungsgrund als Nachricht — das Öffnen degradert nie 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 im IMemoryCache unter einem frischen GUID‑Token mit gleitender Ablaufzeit — DocOptions.TimeOut Minuten, standardmäßig 60 — gespeichert. Jede Seitenanfrage setzt die Uhr zurück.
3. Sicherheitsregistrierung. Mit UnsafeMode = false (Standard) ist das 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. Das Token wird zurückgegeben. Es ist das einzige Anmelde­merkmal für alles, was folgt.

Es gibt keinen separaten Aufwärms‑Schritt. Die vorherige Bibliothek stellte InitCache() zu diesem Zweck bereit; sie existiert nicht mehr, und nichts ersetzt sie.

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).
• Unbekanntes oder abgelaufenes Token → ein Fehl­bild 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 Fehl­bild mit You Are Not Authorized To View This Page.

Wo die Middleware eingebunden wird

UseDoconut() beantwortet Anfragen, die ein Token enthalten, egal wo Sie sie einbinden. Die Referenz‑Anwendung behält die historische DocImage.axd‑Anfrageform auf einem MapWhen‑Zweig bei, sodass ein bestehender Client weiterhin die URL aufruft, die er immer verwendet hat. Was Sie auch wählen, das BasePath des Clients muss damit übereinstimmen — siehe ViewerConfig.

Seiten von gemeinsam genutztem Speicher statt vom öffnenden Knoten zu bedienen, ist eine völlig andere Anordnung; siehe Distributed Deployments.

Schließen eines Dokuments

viewer.CloseDocument(token);

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

Es wird auf dem injizierten Viewer aufgerufen. Das vorherige Muster — ein kurzlebiges Viewer in einem using‑Block zu konstruieren, nur um ein Token zu schließen — hat kein Äquivalent und ist nicht nötig.

Fazit

• Ein geöffnetes Dokument = eine Sitzung = ein Token. Token sind pro Browsersitzung, nicht globale URLs.
• Das Token läuft nach einem gleitenden Fenster ab; ein Viewer, der länger als DocOptions.TimeOut untätig ist, muss erneut geöffnet werden.
• Viewer kann injiziert und frei geteilt werden; Sitzungen tragen den gesamten Zustand.