Wie der Viewer funktioniert
Der Lebenszyklus einer Dokumentanfrage
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, …), stets authentifiziert durch das Token.
Viewer ist zustandslos — nach Design
Viewer ist versiegelt, hält keinen zustandsbezogenen Dokumenten‑State pro Anfrage und implementiert bewusst nicht IDisposable. Sitzungen leben unabhängig im Sitzungs‑Manager und werden durch Cache‑Ablauf oder ein explizites CloseDocument(token) bereinigt.
Sie konstruieren es nicht mehr. AddDoconut() registriert es als transiente 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 übergeben Sie es als Konstruktorparameter; in einer Razor‑View verwenden Sie
@inject Doconut.Viewer Viewer. Anwendungs‑eigene Caches von Viewer‑Instanzen sind nicht mehr nötig — und zudem nicht korrekt, weil sie nichts enthalten, das einen Cache rechtfertigt.
Was passiert innerhalb von OpenDocumentAsync
- Lizenz‑Gate. 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 übergeben wird — ein Öffnen degradert nie stillschweigend bei einer ungültigen (im Gegensatz zu fehlenden) Lizenz. Eine kalender‑abgelaufene temporäre oder Abonnement‑Lizenz ist die Ausnahme: Sie wirft keinen Fehler — sie degradert 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 gleitender 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 Anmelde‑Credential für alles, was folgt.
Es gibt keinen separaten Aufwärms‑Schritt. Die vorherige Bibliothek stellte dafür InitCache() bereit; sie existiert nicht mehr und nichts ersetzt sie.
Die drei Überladungen unterscheiden sich nur im Eingabetyp: ein Dateipfad, ein Dateipfad plus eine format‑spezifische 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 im Query‑String auf. Was die Middleware tut, hängt von der Anfrage ab:
| Query | Zweck |
|---|---|
?token=…&page=N | Gerendertes Seitenbild (PNG) |
?token=…&page=N&thumb=1 | Miniaturbild |
?token=…&zoom=… | Vergrößerte Seitenrenderung |
?token=…&search=term | Volltextsuche (lizenzgesteuert) |
?token=…&bookmarks | Dokumenten‑Gliederung/Lesezeichen |
?token=…© / &showlinks / &fileFormat | Textkopie, Hyperlinks und Format‑Informationen |
?token=…&meta | DICOM‑technische Metadaten; gibt 501 für eine DICOM‑Sitzung in diesem Paket zurück |
?token=…&action=rotate/flip/close | Seiten‑Aktionen und explizites Schließen |
?token=…&AnnSave=… / &AnnLoad | Anmerkungen speichern/laden |
Jeder dieser Pfade prüft zuerst:
- Kein Token → die Middleware gibt 404 zurück (oder ein Versions‑Banner, wenn
ShowDoconutInfo = true). - Unbekanntes oder abgelaufenes Token → ein Fehlermotiv 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 Fehlermotiv mit
You Are Not Authorized To View This Page.
Wo die Middleware eingebunden wird
UseDoconut() beantwortet Anfragen, die ein Token tragen, egal wo Sie sie mounten. Ein gängiges Setup behält die historische DocImage.axd‑Anfrageform auf einem MapWhen‑Zweig bei, sodass ein bestehender Client weiterhin die URL verwendet, 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 ein völlig anderes Arrangement; siehe Distributed Deployments.
Schließen eines Dokuments
viewer.CloseDocument(token);CloseDocument entfernt die Sitzung aus dem Cache (was die zugrunde liegende Dokument‑Engine entsorgt und deren Speicher sofort freigibt), löscht den secure-{token}‑Marker und widerruft das Zugriffs‑Grant. Der Aufruf ist optional — die gleitende Ablaufzeit erledigt dieselbe Bereinigung automatisch — bei großen Dokumenten ist es jedoch die höfliche Art, den Speicher sofort freizugeben, sobald der Benutzer fertig ist.
Er wird auf dem injizierten Viewer aufgerufen. Das frühere Muster — eine kurzlebige Viewer in einem using‑Block ausschließlich zum Schließen eines Tokens zu konstruieren — hat kein Äquivalent und wird nicht mehr benötigt.
Fazit
- Ein geöffnetes Dokument = eine Sitzung = ein Token. Tokens sind pro Browsersitzung, nicht globale URLs.
- Das Token läuft nach 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?