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 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 registrierte Plugin-Berechtigungen beim Start; das Zurückfallen der Fabrik auf den integrierten Viewer ist eine defensive Laufzeitregel.
3. Nur-Plugin-Formate. Für einige Erweiterungen gibt es 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 Katalog-Standard 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 — auf Kosten einer Vorabkonvertierung 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 — angewendet 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. 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 jeder nachfolgenden Darstellung dieser Seite angewendet.
• Skalieren — Miniaturansichten und Zoomstufen werden erzeugt, indem die gerenderte Seite auf die gewünschte Zielgröße skaliert wird; 0 bedeutet Auslieferung in Originalgröße.
• Annotation einbrennen — gespeicherte Anmerkungen werden auf das Bitmap gezeichnet, sodass Exporte und Seitenbilder sie anzeigen.
• Kodierung — das Ergebnis wird mit Hilfe von gepoolten Speicher‑Streams zu 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 Dauer der Dokumentsitzung, sodass ein erneuter Besuch einer Seite sie nicht erneut rendert. BaseConfig.ImageResolution (25–300 DPI, 0 = Format‑Standard) ist das Hauptinstrument für Qualität/Speicher; der Standard jedes Formats ist auf seiner Konfigurationsseite dokumentiert.

DocOptions.ImageResolution ist veraltet und beeinflusst die Renderqualität nicht. Wenn Sie eine Anwendung aus der vorherigen Bibliothek weiterführen, verschieben Sie diesen Wert in die Formatkonfiguration — der Compiler wird auf jede Aufrufstelle hinweisen.

Rendering auf einem Knoten vs. vielen

Alles oben Beschriebene bezieht sich auf das Rendering auf einem einzelnen Knoten bei Bedarf für die Sitzung, die das Dokument geöffnet hat. Eine Bereitstellung, bei der ein Knoten das gesamte Artefakt‑Set rendert und veröffentlicht und andere Knoten diese Seiten aus gemeinsamem Speicher bereitstellen, verwendet einen anderen Lesepfad — siehe Verteilte Bereitstellungen.

Wo man was einstellt