Pipeline di Rendering

Tra OpenDocumentAsync e il PNG che arriva al 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 ciascuna immagine di pagina ad ogni richiesta a DocImage.axd). 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 factory associa l'estensione del file a un visualizzatore tramite il catalogo dei formati, con tre livelli di precedenza:

1. Prima i visualizzatori personalizzati. Qualsiasi cosa tu abbia registrato con DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) ha la precedenza su tutti quelli 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 di motore. Se un plugin con licenza fornisce un visualizzatore per la stessa estensione, il visualizzatore del plugin sostituisce quello integrato.
3. Formati solo plugin. Alcune estensioni non hanno alcun visualizzatore integrato — DICOM (.dcm, .ima) 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.

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 PDF in memoria, il motore sorgente viene rilasciato e un visualizzatore PDF prende il controllo. Il PDF generato contiene testo reale, così la ricerca full‑text ottiene evidenziazioni native esatte; la pipeline attiva AllowSearch e AllowCopy per il PDF reindirizzato, poiché la conversione è invisibile all'utente.

XPS e MHT, per impostazione predefinita, usano il percorso di reindirizzamento. Una proiezione PDF fornisce ricerca nativa a formati come HTML e Microsoft Project. Se il PDF risultante contiene immagini senza livello di testo, quei pixel non possono essere ricercati.

Usa la modalità di reindirizzamento quando ti serve una proiezione ricercabile e con testo — al costo di una conversione iniziale quando il documento si apre.

Fase 2 — La pipeline di immagini di pagina

Ogni richiesta di pagina a DocImage.axd esegue una sequenza fissa:

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

• Watermark — applicata dallo stato della licenza (nessuna licenza, licenza temporanea o di abbonamento scaduta, dominio non valido, build al di fuori delle versioni della licenza) e da DocOptions.Watermark per il tuo testo. Un sito con licenza senza watermark personalizzato salta questo passaggio.
• Rotate/flip — lo stato per pagina impostato dall'utente nel widget (90°/180°/270°, capovolgimenti orizzontali e verticali) è memorizzato nella sessione e applicato a ogni successiva renderizzazione di quella pagina.
• Scale — le miniature e i livelli di zoom sono prodotti scalando la pagina renderizzata alla dimensione richiesta.
• Annotation burn — le annotazioni salvate sono disegnate sul bitmap, così le esportazioni e le immagini di pagina le mostrano.
• Encoding — il risultato è codificato come PNG e scritto direttamente nella risposta.

Gli errori all'interno del gestore vengono restituiti come immagini di errore PNG (testo rosso su bianco) con stato 200, 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 di pagina renderizzate in memoria per la durata della sessione del documento, così rivedere una pagina non la rende nuovamente. BaseConfig.ImageResolution (25–300 DPI, 0 = il valore predefinito del formato) è il principale controllo di qualità e memoria; il valore predefinito di ogni formato è elencato in Configurazioni dei Formati.

Su un singolo nodo, le sessioni e le pagine cache vivono nella memoria del processo worker. Un riciclo del pool di applicazioni — programmato, o attivato da una modifica a Web.config o da un timeout inattivo — elimina ogni sessione di documento aperta, e il widget mostra quindi Document session not found. Please re-open document. In modalità distribuita (vedi Sessioni e Sicurezza), una sessione viene ricostruita dallo store condiviso.

Dove regolare cosa