Pipeline di Rendering

Tra OpenDocumentAsync e il PNG che raggiunge il browser ci sono due fasi distinte: risoluzione del visualizzatore (qual è il motore che 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 DefaultRender cambia realmente.

Fase 1 — Risoluzione del visualizzatore di formato

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

1. Visualizzatori personalizzati prima. Qualsiasi cosa tu abbia registrato con DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) prevale su tutti i visualizzatori integrati.
2. Visualizzatori di famiglia integrati. Il catalogo mappa 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 si dichiara responsabile genera:

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

Dopo la risoluzione, la configurazione è definita: 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 forza 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 della 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

• Watermark — applicato dallo stato della licenza (licenza mancante, temporanea o di abbonamento scaduta, dominio non valido, versione errata) e da DocOptions.Watermark per il tuo testo personalizzato. Un'app correttamente licenziata — o una licenza Temporanea attiva — senza watermark personalizzato salta questo passaggio.
• Rotate/flip — lo stato per pagina impostato dall'utente nel widget (90°/180°/270°, capovolgimenti orizzontali/verticali) è memorizzato nella sessione e applicato ad ogni successiva renderizzazione di quella pagina.
• Scale — le miniature e i livelli di zoom sono prodotti scalando la pagina renderizzata alla dimensione target richiesta; 0 significa servire alla dimensione originale.
• Annotation burn — le annotazioni salvate sono disegnate sul bitmap in modo che le esportazioni e le immagini delle pagine le mostrino.
• Encoding — 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 PNG error images (testo rosso su bianco) invece di pagine di errore HTTP, così il widget può visualizzarli nell'area della pagina.

Cache delle pagine

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

Dove regolare cosa