Pipeline di Rendering

Tra OpenDocumentAsync e il PNG che raggiunge il browser ci sono due fasi distinte: risoluzione del visualizzatore (quale motore carica il documento, deciso una volta per apertura) e elaborazione della pagina (cosa succede a ogni immagine di pagina ad ogni richiesta). Conoscere entrambe spiega perché un formato viene renderizzato in un certo modo — e cosa cambia realmente DefaultRender.

Fase 1 — Risoluzione del visualizzatore di formato

La fabbrica associa l'estensione del file a un visualizzatore tramite il catalogo dei formati, con tre livelli di precedenza:

1. Visualizzatori personalizzati per primi. Qualsiasi cosa tu abbia registrato con DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) prevale su tutti i visualizzatori integrati.
2. Visualizzatori di famiglia integrati. Il catalogo associa ogni estensione visualizzabile a una famiglia di visualizzatori — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — ognuna con il proprio adattatore del motore. Se un plugin con licenza contribuisce con un visualizzatore per la stessa estensione, il visualizzatore del plugin sostituisce quello integrato. AddDoconut() convalida i diritti dei plugin registrati all'avvio; il fallback della fabbrica al visualizzatore integrato è una regola difensiva a runtime.
3. Formati solo plugin. Alcune estensioni non hanno alcun visualizzatore integrato — DICOM (.dcm) esiste solo tramite il plugin DICOM. Aprirne uno senza la capacità richiesta genera:

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

Un'estensione per la quale nessun visualizzatore è disponibile genera:

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

Dopo la risoluzione, la configurazione è stabilita: il tuo oggetto di configurazione esplicito se ne hai fornito uno, altrimenti la configurazione predefinita del formato dal catalogo. DocOptions.Password viene copiato nella configurazione per i documenti protetti.

Fase 1b — Modalità di reindirizzamento (DefaultRender = false)

La maggior parte delle configurazioni per formato espone un flag DefaultRender. Seleziona tra due percorsi fondamentalmente diversi:

• DefaultRender = true — il documento viene renderizzato nativamente, direttamente in immagini di pagina.
• DefaultRender = false — il documento viene prima convertito in un PDF in memoria, il motore sorgente viene rilasciato e un visualizzatore PDF prende il controllo. Il PDF generato incorpora testo reale, così la ricerca full‑text ottiene evidenziazioni native a livello di pixel; la pipeline imposta AllowSearch e AllowCopy per il PDF reindirizzato poiché la conversione è invisibile all'utente.

XPS e il valore predefinito del catalogo per MHT utilizzano il percorso di reindirizzamento. Una proiezione PDF può fornire ricerca nativa per formati come HTML e Microsoft Project. Se il PDF risultante contiene immagini senza uno strato di testo, il visualizzatore standard non può cercare quei pixel.

Usa la modalità di reindirizzamento quando hai bisogno di una proiezione PDF con testo — al costo di una conversione iniziale quando il documento si apre.

Fase 2 — La pipeline di immagini di pagina

Le pagine renderizzate vengono elaborate per richiesta attraverso una sequenza fissa:

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

• Filigrana — applicata dallo stato della licenza (licenza mancante, temporanea scaduta o abbonamento, dominio non valido, versione errata) e da DocOptions.Watermark per il tuo testo personalizzato. Un'applicazione correttamente licenziata — o una licenza Temporanea attiva — senza filigrana personalizzata salta questo passaggio.
• Ruota/Capovolgi — lo stato per pagina impostato dall'utente nel widget (90°/180°/270°, capovolgimenti orizzontali/verticali) è memorizzato nella sessione e applicato a ogni successiva renderizzazione di quella pagina.
• Scala — le miniature e i livelli di zoom sono prodotti scalando la pagina renderizzata alla dimensione target richiesta; 0 significa servire alla dimensione originale.
• Integrazione delle annotazioni — le annotazioni salvate sono disegnate sul bitmap in modo che le esportazioni e le immagini di pagina le mostrino.
• Codifica — il risultato è codificato in PNG usando stream di memoria condivisi e scritto direttamente nella risposta HTTP.

Gli errori all'interno del middleware vengono restituiti come immagini PNG di errore (testo rosso su bianco) invece di pagine di errore HTTP, così il widget può visualizzarle nell'area della pagina.

Cache delle pagine

BaseConfig.CachePages (predefinito true) mantiene le immagini delle pagine renderizzate in memoria per la durata della sessione del documento, così rivisitare una pagina non la renderizza nuovamente. BaseConfig.ImageResolution (25–300 DPI, 0 = predefinito del formato) è il principale controllo qualità/memoria; il valore predefinito di ogni formato è documentato nella sua pagina di configurazione.

DocOptions.ImageResolution è obsoleta e non controlla la qualità del rendering. Se stai
portando un'applicazione dalla libreria precedente, sposta quel valore nella configurazione del formato — il compilatore indicherà ogni punto di chiamata.

Rendering su un nodo vs. molti

Tutto quanto sopra descrive il rendering su un singolo nodo su richiesta per la sessione che ha aperto
il documento. Un'implementazione in cui un nodo renderizza e pubblica l'intero set di artefatti,
e gli altri nodi servono quelle pagine da storage condiviso, utilizza un percorso di lettura diverso — vedi
Distribuzioni distribuite.

Dove regolare cosa