Render-Pipeline

Zwischen OpenDocumentAsync und dem PNG, das den Browser erreicht, gibt es zwei getrennte Phasen: Viewer‑Auflösung (welcher Engine das Dokument lädt, einmal pro Öffnung entschieden) und Seitenverarbeitung (was mit jedem Seitenbild bei jeder Anforderung 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 Fabrik 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. Integrierte 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 Plugin‑Viewer den integrierten. AddDoconut() prüft die registrierten Plugin‑Berechtigungen beim Start; das Zurückfallen der Fabrik auf den integrierten Viewer ist eine defensive Laufzeitregel.
3. Nur‑Plugin‑Formate. Einige Erweiterungen haben überhaupt keinen integrierten Viewer – DICOM (.dcm) 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 vorhanden ist, löst aus:

FormatNotSupportedException: Document format '<extension>' is not supported.

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 bettet echten Text ein, sodass die Volltextsuche pixelgenaue native Hervorhebungen erhält; die Pipeline erzwingt AllowSearch und AllowCopy für das weitergeleitete PDF, da die Konvertierung für den Benutzer unsichtbar ist.

XPS und der Katalogstandard für MHT verwenden den Weiterleitungspfad. Eine PDF‑Projektion kann native Suche für Formate wie HTML und Microsoft Project bereitstellen. Enthält das resultierende PDF Bilder ohne Textebene, kann der Standard‑Viewer diese Pixel nicht durchsuchen.

Verwenden Sie den Weiterleitungsmodus, wenn Sie eine PDF‑Projektion mit Text benötigen – zu Lasten einer anfänglichen Konvertierung beim Öffnen des Dokuments.

Stufe 2 — Die Seitenbild‑Pipeline

Gerenderte Seiten werden pro Anforderung durch eine feste Sequenz verarbeitet:

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

• Wasserzeichen — wird basierend auf dem Lizenzstatus (fehlende Lizenz, abgelaufene temporäre oder Abonnement‑Lizenz, ungültige Domain, falsche Version) und aus DocOptions.Watermark für Ihren eigenen Text angewendet. Eine korrekt lizenzierte Anwendung – oder eine aktive temporäre Lizenz – ohne benutzerdefiniertes Wasserzeichen überspringt diesen Schritt.
• Drehen/Spiegeln — der pro Seite festgelegte Zustand, den der Benutzer im Widget einstellt (90°/180°/270°, horizontale/vertikale Spiegelungen), wird in der Sitzung gespeichert und bei jedem nachfolgenden Rendern dieser Seite angewendet.
• Skalieren — Thumbnails und Zoomstufen werden erzeugt, indem die gerenderte Seite auf die gewünschte Zielgröße skaliert wird; 0 bedeutet, in Originalgröße auszuliefern.
• Anmerkungen einbrennen — gespeicherte Anmerkungen werden auf das Bitmap gezeichnet, sodass Exporte und Seitenbilder sie anzeigen.
• Kodierung — das Ergebnis wird mit gepoolten Memory‑Streams in PNG kodiert und direkt in die HTTP‑Antwort geschrieben.

Fehler innerhalb der Middleware werden als PNG‑Fehlerbilder (roter Text auf weiß) zurückgegeben, anstatt 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 = Formatstandard) ist das Haupt‑Qualitäts‑/Speicherregler; der Standard jedes Formats ist auf seiner Konfigurationsseite dokumentiert.

Wo man was einstellt