Renderovací pipeline

Mezi OpenDocumentAsync a PNG, která dorazí do prohlížeče, jsou dva odlišné kroky: rozlišení prohlížeče (který engine načte dokument, rozhodnuto jednou při otevření) a zpracování stránky (co se děje s každým obrázkem stránky při každém požadavku). Znalost obou vysvětluje, proč se formát vykresluje tak, jak to dělá — a co DefaultRender ve skutečnosti přepíná.

Krok 1 — Rozlišení prohlížeče formátu

Továrna mapuje příponu souboru na prohlížeč pomocí katalogu formátů, se třemi úrovněmi precedence:

1. Vlastní prohlížeče první. Cokoliv, co jste zaregistrovali pomocí DoconutOptions.RegisterViewer(extension, factory, defaultConfig?), má přednost před všemi vestavěnými.
2. Vestavěné prohlížeče rodin. Katalog mapuje každou zobrazitelnou příponu na rodinu prohlížečů — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — každá s vlastním adaptérem engine. Pokud licencovaný plugin poskytne prohlížeč pro stejnou příponu, prohlížeč pluginu nahradí vestavěný. AddDoconut() ověřuje registrovaná oprávnění pluginů při spuštění; fallback továrny na vestavěný prohlížeč je obranné pravidlo za běhu.
3. Formáty pouze pro pluginy. Některé přípony nemají vůbec vestavěný prohlížeč — DICOM (.dcm) existuje jen prostřednictvím DICOM pluginu. Otevření takového souboru bez požadované schopnosti vyvolá výjimku:

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

Rozšíření, pro které neexistuje žádný prohlížeč, vyvolá:

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

Po rozlišení je konfigurace ustavena: váš explicitní konfigurační objekt, pokud jste jej předali, jinak výchozí konfigurace formátu z katalogu. DocOptions.Password je zkopírováno do konfigurace pro chráněné dokumenty.

Krok 1b — Režim přesměrování (DefaultRender = false)

Většina konfigurací na formát odhaluje příznak DefaultRender. Ten vybírá mezi dvěma zásadně odlišnými cestami:

• DefaultRender = true — dokument se vykresluje nativně, přímo na obrázky stránek.
• DefaultRender = false — dokument je nejprve převáděn do PDF v paměti, zdrojový engine je uvolněn a převzet PDF prohlížeč. Vygenerované PDF obsahuje skutečný text, takže full‑textové vyhledávání získá pixelově přesné nativní zvýraznění; pipeline vynutí zapnutí AllowSearch a AllowCopy pro přesměrované PDF, protože konverze je pro uživatele neviditelná.

XPS a výchozí katalog pro MHT používají cestu přesměrování. PDF projekce může poskytnout nativní vyhledávání pro formáty jako HTML a Microsoft Project. Pokud výsledné PDF obsahuje obrázky bez textové vrstvy, standardní prohlížeč nemůže vyhledávat v těchto pixelech.

Použijte režim přesměrování, když potřebujete PDF projekci s textem — za cenu úvodní konverze při otevření dokumentu.

Krok 2 — Pipeline obrázků stránek

Vykreslené stránky jsou při každém požadavku zpracovány pevnou sekvencí:

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

• Vodoznak — aplikován podle stavu licence (chybějící licence, vypršená dočasná nebo předplatná, neplatná doména, špatná verze) a z DocOptions.Watermark pro váš vlastní text. Správně licencovaná aplikace — nebo aktivní dočasná licence — bez vlastního vodoznaku tento krok přeskočí.
• Otočení/převrácení — stav na stránce, který uživatel nastaví ve widgetu (90°/180°/270°, horizontální/vertikální převrácení) je uložen v relaci a aplikován při každém dalším vykreslení té stránky.
• Škálování — miniatury a úrovně přiblížení jsou vytvořeny škálováním vykreslené stránky na požadovanou cílovou velikost; 0 znamená podávat v původní velikosti.
• Vypálení anotací — uložené anotace jsou vykresleny na bitmapu, takže exporty a obrázky stránek je zobrazí.
• Kódování — výsledek je zakódován do PNG pomocí sdílených paměťových streamů a zapsán přímo do HTTP odpovědi.

Chyby uvnitř middleware jsou vráceny jako PNG obrázky chyb (červený text na bílém) místo HTTP chybových stránek, takže widget je může zobrazit v oblasti stránky.

Cacheování stránek

BaseConfig.CachePages (výchozí true) uchovává vykreslené obrázky stránek v paměti po dobu životnosti relace dokumentu, takže opětovná návštěva stránky nevyvolá nové vykreslení. BaseConfig.ImageResolution (25–300 DPI, 0 = výchozí formátu) je hlavní ovladač kvality/paměti; výchozí hodnota každého formátu je zdokumentována na jeho konfigurační stránce.

DocOptions.ImageResolution je zastaralý a neovlivňuje kvalitu vykreslování. Pokud přenášíte aplikaci z předchozí knihovny, přesuňte tuto hodnotu do konfigurace formátu — kompilátor ukáže na každé místo volání.

Vykreslování na jednom uzlu vs. více uzlech

Vše výše popsané se týká vykreslování na jednom uzlu na vyžádání pro relaci, která dokument otevřela. Nasazení, kde jeden uzel vykresluje a publikuje celý soubor artefaktů, a ostatní uzly slouží tyto stránky ze sdíleného úložiště, používá jinou čtecí cestu — viz Distribuovaná nasazení.

Kde co ladit