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:

csharp
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. 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.
  2. 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 IMemoryCache unter einem frischen GUID‑Token mit einer gleitenden Ablaufzeit gespeichert — DocOptions.TimeOut Minuten, Standard 60. Jede Seitenanfrage setzt die Uhr zurück.
  3. Sicherheitsregistrierung. Mit UnsafeMode = false (dem Standard) wird 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 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 Format­erkennung 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:

AbfrageZweck
?token=…&page=NGerendertes Seitenbild (PNG)
?token=…&page=N&thumb=1Vorschaubild
?token=…&zoom=…Vergrößerte Seitenrendering
?token=…&search=termVolltextsuche (lizenzgesteuert)
?token=…&bookmarksDokumentgliederung/Lesezeichen
?token=…&copy / &showlinks / &fileFormat / &metaTextkopie, Hyperlinks, Formatinformationen, DICOM‑technische Metadaten
?token=…&action=rotate/flip/closeSeitenaktionen und explizites Schließen
?token=…&AnnSave=… / &AnnLoadAnnotationen 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 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.

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

csharp
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.TimeOut untätig ist, muss erneut geöffnet werden.
  • Viewer kann injiziert und frei geteilt werden; Sitzungen tragen den gesamten Zustand.

War diese Seite hilfreich?