Wie der Viewer funktioniert
Der Lebenszyklus von Dokumentanfragen
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‑Tokens zurück.- Die Dokumentensitzung — ein serverseitiges Objekt, das das geladene Dokument hält, indiziert durch ein Token in
IMemoryCache. - Die Doconut‑Middleware — hinzugefügt von
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 existieren unabhängig im Sitzungs‑Manager und werden durch Cache‑Ablauf oder ein explizites CloseDocument(token) bereinigt.
Injizieren Sie es, wo immer 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
- Lizenzschranke. Eine abgelehnte oder versionsabgelaufene Lizenz (auf der schwarzen Liste, manipuliert oder ein Build außerhalb des Lizenz‑Update‑Fensters) wirft sofort ein
LicenseException, wobei der Ablehnungsgrund als Nachricht übermittelt wird — 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 keinen Fehler — sie degradiert zu einem Wasserzeichen. - Sitzungserstellung. Die Viewer‑Factory wählt den passenden Format‑Viewer für die Dateierweiterung und lädt das Dokument (siehe Rendering‑Pipeline). Die Sitzung wird in
IMemoryCacheunter einem frischen GUID‑Token mit einer gleitenden Ablaufzeit gespeichert —DocOptions.TimeOutMinuten, Standard 60. Jede Seitenanfrage setzt die Uhr zurück. - Sicherheitsregistrierung. Mit
UnsafeMode = false(dem Standard) wird das Token an die ASP.NET‑Sitzung des Aufrufers gebunden: einsecure-{token}‑Marker wird in die Sitzung geschrieben, sodass nur die Browsersitzung, die das Dokument geöffnet hat, dessen Seiten anfordern kann. - Das Token wird zurückgegeben. Es ist das einzige Anmeldezeichen für alles, was danach folgt.
Die drei Überladungen unterscheiden sich nur im Eingabewert: ein Dateipfad, ein Dateipfad plus eine formatbezogene Konfiguration (PdfConfig, WordConfig, …) oder ein Stream plus ein FileInfo, dessen Erweiterung die Formaterkennung steuert.
Wie das Widget Seiten erhält
Das Client‑Widget ruft die Doconut‑Middleware mit dem Token in der Abfragezeichenkette auf. Was die Middleware tut, hängt von der Anfrage ab:
| Abfrage | Zweck |
|---|---|
?token=…&page=N | Gerendertes Seitenbild (PNG) |
?token=…&page=N&thumb=1 | Vorschaubild |
?token=…&zoom=… | Vergrößerte Seitenrendering |
?token=…&search=term | Volltextsuche (lizenzgesteuert) |
?token=…&bookmarks | Dokumentgliederung/Lesezeichen |
?token=…© / &showlinks / &fileFormat / &meta | Textkopie, Hyperlinks, Formatinformationen, DICOM‑technische Metadaten |
?token=…&action=rotate/flip/close | Seitenaktionen und explizites Schließen |
?token=…&AnnSave=… / &AnnLoad | Annotationen speichern/laden |
Jeder dieser Pfade wird zuerst validiert:
- Kein Token → die Middleware gibt 404 zurück (oder ein Versionsbanner, wenn
ShowDoconutInfo = true). - Unbekanntes oder abgelaufenes Token → ein Fehlbild mit
Document session not found. Please re-open document. - Sitzungs‑Middleware fehlt (mit
UnsafeMode = false) → HTTP 500 mitSession 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.
Das Bereitstellen von Seiten aus gemeinsam genutztem Speicher anstelle des öffnenden Knotens ist eine völlig andere Anordnung; siehe Verteilte Deployments.
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 freizugeben, sobald der Benutzer fertig ist.
Fazit
- Ein geöffnetes Dokument = eine Sitzung = ein Token. Tokens gelten pro Browsersitzung, nicht global für URLs.
- Das Token läuft in einem gleitenden Fenster ab; ein Viewer, der länger als
DocOptions.TimeOutuntätig ist, muss erneut geöffnet werden. Viewerkann injiziert und frei geteilt werden; Sitzungen tragen den gesamten Zustand.
War diese Seite hilfreich?