Render-Pipeline

Zwischen OpenDocumentAsync und dem PNG, das den Browser erreicht, gibt es zwei unterschiedliche Phasen: Viewer‑Auflösung (welche Engine das Dokument lädt, einmal pro Öffnen entschieden) und Seitenverarbeitung (was mit jedem Seitenbild bei jeder Anforderung an DocImage.axd geschieht). Das Verständnis beider erklärt, warum ein Format so rendert, wie es tut — und was DefaultRender wirklich umschaltet.

Stufe 1 — Auflösen des Format‑Viewers

Die Factory ordnet die Dateierweiterung über den Formatkatalog einem Viewer zu, mit drei Prioritätsebenen:

1. Benutzerdefinierte Viewer zuerst. Alles, was Sie mit DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) registriert haben, hat Vorrang vor allen integrierten.
2. Eingebaute Familien‑Viewer. Der Katalog ordnet jede anzeigbare Erweiterung einer Viewer‑Familie zu — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — jeweils mit eigenem Engine‑Adapter. Wenn ein lizenziertes Plugin einen Viewer für dieselbe Erweiterung bereitstellt, ersetzt der Viewer des Plugins den integrierten.
3. Nur‑Plugin‑Formate. Für einige Erweiterungen gibt es keinen integrierten Viewer — DICOM (.dcm, .ima) existiert nur über das DICOM‑Plugin. Das Öffnen ohne die erforderliche Fähigkeit wirft:

LicenseException: This document type requires the 'Dicom' plugin license.

Eine Erweiterung, für die kein Viewer zuständig ist, löst FormatNotSupportedException aus.

Nach der Auflösung ist die Konfiguration festgelegt: Ihr explizites Konfigurationsobjekt, falls Sie eines übergeben haben, andernfalls die Standardkonfiguration des Formats aus dem Katalog. DocOptions.Password wird in die Konfiguration für geschützte Dokumente kopiert.

Stufe 1b — Weiterleitungsmodus (DefaultRender = false)

Die meisten formatbezogenen Konfigurationen stellen ein DefaultRender‑Flag bereit. Es wählt zwischen zwei grundlegend unterschiedlichen Pfaden:

• DefaultRender = true — das Dokument wird nativ gerendert, direkt zu Seitenbildern.
• DefaultRender = false — das Dokument wird zuerst in ein PDF im Speicher konvertiert, die Quell‑Engine wird freigegeben, und ein PDF‑Viewer übernimmt. Das erzeugte PDF enthält echten Text, sodass die Volltextsuche exakte native Hervorhebungen liefert; die Pipeline schaltet AllowSearch und AllowCopy für das weitergeleitete PDF ein, da die Konvertierung für den Benutzer unsichtbar ist.

XPS und MHT verwenden standardmäßig den Weiterleitungsweg. Eine PDF‑Projektion ermöglicht native Suche für Formate wie HTML und Microsoft Project. Enthält das resultierende PDF Bilder ohne Textebene, können diese Pixel nicht durchsucht werden.

Verwenden Sie den Weiterleitungsmodus, wenn Sie eine durchsuchbare, texthaltige Projektion benötigen — zum Preis einer Vorabkonvertierung beim Öffnen des Dokuments.

Stufe 2 — Die Seiten‑Bild‑Pipeline

Jede Seitenanfrage an DocImage.axd führt eine feste Sequenz aus:

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• Wasserzeichen — angewendet basierend auf dem Lizenzstatus (keine Lizenz, abgelaufene temporäre oder Abonnement‑Lizenz, ungültige Domain, Build außerhalb der Lizenz‑Versionen) und aus DocOptions.Watermark für Ihren eigenen Text. Eine lizenzierte Seite ohne benutzerdefiniertes Wasserzeichen überspringt diesen Schritt.
• Drehen/Spiegeln — der pro‑Seite‑Zustand, den der Benutzer im Widget festlegt (90°/180°/270°, horizontale und vertikale Spiegelungen), wird in der Sitzung gespeichert und bei jedem späteren Rendern dieser Seite angewendet.
• Skalieren — Miniaturansichten und Zoom‑Stufen werden erzeugt, indem die gerenderte Seite auf die gewünschte Größe skaliert wird.
• Annotationen einbrennen — gespeicherte Anmerkungen werden auf das Bitmap gezeichnet, sodass Exporte und Seitenbilder sie zeigen.
• Kodierung — das Ergebnis wird als PNG kodiert und direkt in die Antwort geschrieben.

Fehler im Handler werden als PNG‑Fehlerbilder (roter Text auf weiß) mit Status 200 zurückgegeben, anstatt als HTTP‑Fehlerseiten, sodass das Widget sie im Seitenbereich anzeigen kann.

Seiten‑Caching

BaseConfig.CachePages (Standard true) speichert gerenderte Seitenbilder im Speicher für die Lebensdauer der Dokumentsitzung, sodass ein erneuter Besuch einer Seite sie nicht erneut rendert. BaseConfig.ImageResolution (25–300 DPI, 0 = der Standard des Formats) ist das Hauptinstrument für Qualität und Speicher; der Standard jedes Formats ist in Formatkonfigurationen aufgeführt.

Auf einem einzelnen Knoten leben Sitzungen und zwischengespeicherte Seiten im Speicher des Worker‑Prozesses. Ein Recyceln des Anwendungspools — geplant oder ausgelöst durch eine Web.config‑Änderung oder einen Leerlauf‑Timeout — verwirft jede offene Dokumentsitzung, und das Widget zeigt dann Document session not found. Please re-open document. Im verteilten Modus (siehe Sitzungen & Sicherheit) wird eine Sitzung aus dem gemeinsamen Speicher wiederhergestellt.

Wo man was anpasst