Pipeline de rendu

Entre OpenDocumentAsync et le PNG qui atteint le navigateur, il y a deux étapes distinctes : résolution de la visionneuse (quel moteur charge le document, décidé une fois par ouverture) et traitement de la page (ce qui arrive à chaque image de page à chaque requête). Connaître les deux explique pourquoi un format s'affiche de telle manière — et ce que DefaultRender change réellement.

Étape 1 — Résolution de la visionneuse de format

L'usine associe l'extension de fichier à une visionneuse via le catalogue de formats, avec trois niveaux de priorité :

1. Les visionneuses personnalisées d'abord. Tout ce que vous avez enregistré avec DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) l'emporte sur toutes les visionneuses intégrées.
2. Visionneuses de famille intégrées. Le catalogue associe chaque extension affichable à une famille de visionneuses — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — chacune avec son propre adaptateur de moteur. Si un plugin sous licence fournit une visionneuse pour la même extension, la visionneuse du plugin remplace celle intégrée. AddDoconut() valide les droits des plugins enregistrés au démarrage ; le recours de l'usine à la visionneuse intégrée est une règle défensive d'exécution.
3. Formats uniquement via plugin. Certaines extensions n'ont aucune visionneuse intégrée — DICOM (.dcm) n'existe que via le plugin DICOM. En ouvrir une sans la capacité requise génère :

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

Une extension pour laquelle aucune visionneuse ne se revendique lève :

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

Après la résolution, la configuration est définie : votre objet de configuration explicite si vous en avez fourni un, sinon la configuration par défaut du format provenant du catalogue. DocOptions.Password est copié dans la configuration pour les documents protégés.

Étape 1b — Mode de redirection (DefaultRender = false)

La plupart des configurations par format exposent un drapeau DefaultRender. Il sélectionne entre deux chemins fondamentalement différents :

• DefaultRender = true — le document est rendu nativement, directement en images de page.
• DefaultRender = false — le document est d'abord converti en PDF en mémoire, le moteur source est libéré, et une visionneuse PDF prend le relais. Le PDF généré intègre du texte réel, ainsi la recherche en texte intégral obtient des surlignages natifs pixel‑précis ; le pipeline force AllowSearch et AllowCopy à true pour le PDF redirigé puisque la conversion est invisible pour l'utilisateur.

XPS et le paramètre par défaut du catalogue pour MHT utilisent le chemin de redirection. Une projection PDF peut offrir une recherche native pour des formats tels que HTML et Microsoft Project. Si le PDF résultant contient des images sans couche de texte, la visionneuse standard ne peut pas rechercher ces pixels.

Utilisez le mode de redirection lorsque vous avez besoin d'une projection PDF contenant du texte — au prix d'une conversion initiale lors de l'ouverture du document.

Étape 2 — Le pipeline d'images de page

Les pages rendues sont traitées à chaque requête selon une séquence fixe :

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

• Filigrane — appliqué à partir de l'état de la licence (licence manquante, temporaire ou d'abonnement expirée, domaine invalide, mauvaise version) et depuis DocOptions.Watermark pour votre texte personnalisé. Une application correctement licenciée — ou une licence Temporaire active — sans filigrane personnalisé saute cette étape.
• Rotation/retournement — l'état par page que l'utilisateur définit dans le widget (90°/180°/270°, retournements horizontal/vertical) est stocké dans la session et appliqué à chaque rendu ultérieur de cette page.
• Échelle — les miniatures et niveaux de zoom sont produits en redimensionnant la page rendue à la taille cible demandée ; 0 signifie servir à la taille originale.
• Gravure d'annotation — les annotations enregistrées sont dessinées sur le bitmap afin que les exportations et les images de page les affichent.
• Encodage — le résultat est encodé en PNG en utilisant des flux mémoire mis en pool et écrit directement dans la réponse HTTP.

Les erreurs à l'intérieur du middleware sont renvoyées sous forme d'images d'erreur PNG (texte rouge sur fond blanc) plutôt que de pages d'erreur HTTP, afin que le widget puisse les afficher dans la zone de la page.

Mise en cache des pages

BaseConfig.CachePages (par défaut true) conserve les images de pages rendues en mémoire pendant toute la durée de la session du document, de sorte que revisiter une page ne la rend pas à nouveau. BaseConfig.ImageResolution (25–300 DPI, 0 = défaut du format) est le principal réglage qualité/mémoire ; le défaut de chaque format est documenté sur sa page de configuration.

Où ajuster quoi