Wie der Viewer funktioniert

Doconut rendert Dokumente als paginierte Bilder, die von einem HTTP‑Handler bereitgestellt werden, den Ihre Web.config registriert. Das Verständnis des Lebenszyklus — öffnen, Token, Seitenanfragen, schließen — erklärt fast jedes Verhalten, das Sie beobachten werden, einschließlich der Fehlermeldungen.

Die Komponenten

• Viewer — der öffentliche Dienst, den Sie aus DoconutHost.Services auflösen. Er öffnet Dokumente und gibt Sitzungs‑Token zurück.
• Die Dokumentensitzung — ein serverseitiges Objekt, das das geladene Dokument hält, im Speicher unter seinem Token.
• DocImage.axd — der in Web.config deklarierte Doconut.DocImageHandler. Er beantwortet jede Anfrage, die das Browser‑Widget stellt (Seiten, Thumbnails, Suche, Anmerkungen, …), immer identifiziert durch das Token.
• /doconut-res/* — das Doconut.DoconutResourceModule, das die eigenen Skripte, Styles und Icons des Widgets bereitstellt.

Viewer ist zustandslos — per Design

Viewer hält keinen pro‑Anfrage‑Dokumentzustand und implementiert kein IDisposable. Sitzungen existieren unabhängig davon und werden bei Ablauf oder durch ein explizites CloseDocument(token) bereinigt. System.Web unterstützt keine Konstruktor‑Injection, daher lösen Sie ihn dort auf, wo Sie ihn benötigen — typischerweise in einer Controller‑Action:

// POST /ViewerApi/Open?fileName=Sample.pdf
[HttpPost]
public async Task<ActionResult> Open(string fileName)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    var path   = Server.MapPath("~/files/" + Path.GetFileName(fileName));

    var token = await viewer.OpenDocumentAsync(path);
    return Content(token, "text/plain");
}

Was passiert innerhalb von OpenDocumentAsync

1. Lizenzprüfung. Ein abgelehntes Lizenz‑Token (manipuliert, gesperrt oder ein Build außerhalb des Lizenz‑Update‑Fensters) wirft sofort LicenseException mit dem Grund als Fehlermeldung. Ein Öffnen degradiert nie stillschweigend bei einer ungültigen Lizenz; eine fehlende Lizenz fügt nur ein Wasserzeichen hinzu.
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 im Speicher unter einem neuen zufälligen Token mit einer gleitenden Ablaufzeit von DocOptions.TimeOut Minuten (Standard 60) abgelegt. Jede Seitenanfrage setzt die Uhr zurück.
3. Zugriffsgewährung. Bei UnsafeMode = false (Standard) ist das Token an die ASP.NET‑Sitzung der anfordernden Anfrage gebunden: ein secure-{token}‑Eintrag wird in dieser Sitzung geschrieben. Das Öffnen muss daher in einer Anfrage mit Session‑State erfolgen — siehe Sessions & Security.
4. Das Token wird zurückgegeben. Es ist der einzige Identifier, den der Browser für alles Weitere benötigt.

Die asynchronen Überladungen akzeptieren einen Dateipfad, einen Dateipfad plus eine format‑spezifische Konfiguration (PdfConfig, WordConfig, …) oder einen Stream plus ein FileInfo, dessen Erweiterung das Format bestimmt. Für Web‑Forms‑Code‑Behind, das keine asynchronen Seiten nutzt, bietet OpenDocument dieselben drei Eingaben synchron an (Pfad, Stream mit Dateinamen oder Byte‑Array mit Dateinamen).

Wie das Widget Seiten erhält

Das Widget ruft DocImage.axd mit dem Token in der Query‑Zeichenkette auf. Was der Handler tut, hängt von der Anfrage ab:

Jede Anfrage wird zuerst geprüft:

• Kein Token → 404, oder ein Versionsbanner, wenn ShowDoconutInfo = true.
• Token nicht für diese ASP.NET‑Sitzung freigegeben → ein Fehlermotiv mit dem Text You Are Not Authorized To View This Page.
• Unbekanntes oder abgelaufenes Token → ein Fehlermotiv mit dem Text Document session not found. Please re-open document.

Die Fehlermotive sind gewöhnliche PNG‑Dateien, die mit dem Status 200 gesendet werden, sodass das Widget sie dort anzeigen kann, wo die Seite stehen würde. Ein Monitoring‑Check, der nur den Statuscode betrachtet, meldet sie als ausgelieferte Seiten; eine echte Seite hat mehrere zehn bis hundert Kilobyte, ein Fehlermotiv etwa 2 KB.

Schließen eines Dokuments

viewer.CloseDocument(token);

CloseDocument entfernt die Sitzung (gibt die Dokument‑Engine und deren Speicher sofort frei), löscht den secure-{token}‑Eintrag aus der aktuellen ASP.NET‑Sitzung und widerruft das Token. Es ist optional — die gleitende Ablaufzeit erledigt dieselbe Bereinigung —, aber bei großen Dokumenten wird so der Speicher sofort freigegeben, sobald der Benutzer fertig ist. Vom Browser aus sendet objViewer.Close(true) die entsprechende Schließ‑Anfrage an DocImage.axd.

Wichtige Erkenntnisse

• Ein geöffnetes Dokument = eine Sitzung = ein Token, das der ASP.NET‑Sitzung, die es geöffnet hat, zugewiesen wird.
• Das Token läuft in einem gleitenden Zeitfenster ab; ein Viewer, der länger als DocOptions.TimeOut untätig ist, muss erneut geöffnet werden.
• Viewer kann frei aufgelöst und geteilt werden; die Sitzungen tragen den gesamten Zustand.