Render-Pipeline

Zwischen OpenDocumentAsync und dem PNG, das den Browser erreicht, gibt es zwei unterschiedliche Stufen: Viewer-Auflösung (welche Engine das Dokument lädt, einmal pro Öffnung entschieden) und Seitenverarbeitung (was mit jedem Seitenbild bei jeder Anforderung geschieht). Das Wissen über beide 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. 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 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, sonst 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 Weiterleitungsweg. 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 sofortigen Konvertierung beim Öffnen des Dokuments.

Stufe 2 — Die Seiten‑Bild‑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 Zoom‑Stufen 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 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) hält gerenderte Seitenbilder im Speicher für die Dauer der Dokumentsitzung, sodass ein erneuter Besuch einer Seite sie nicht neu rendert. BaseConfig.ImageResolution (25–300 DPI, 0 = Formatstandard) ist das Hauptregler für Qualität/Speicher; der Standard jedes Formats ist auf seiner Konfigurationsseite dokumentiert.

Wo man was einstellt