Canal de Renderizado

Entre OpenDocumentAsync y el PNG que llega al navegador hay dos etapas distintas: resolución del visor (qué motor carga el documento, decidido una vez por apertura) y procesamiento de página (qué ocurre con cada imagen de página en cada solicitud). Conocer ambas explica por qué un formato se renderiza de la manera que lo hace — y lo que realmente cambia DefaultRender.

Etapa 1 — Resolviendo el visor de formato

La fábrica asigna la extensión de archivo a un visor mediante el catálogo de formatos, con tres niveles de precedencia:

1. Visores personalizados primero. Cualquier cosa que hayas registrado con DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) gana sobre cualquier incorporado.
2. Visores de familia incorporados. El catálogo asigna cada extensión visible a una familia de visor — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — cada una con su propio adaptador de motor. Si un plugin con licencia aporta un visor para la misma extensión, el visor del plugin reemplaza al incorporado. AddDoconut() valida los derechos de los plugins registrados al iniciar; la alternativa de la fábrica al visor incorporado es una regla defensiva en tiempo de ejecución.
3. Formatos solo de plugin. Algunas extensiones no tienen visor incorporado — DICOM (.dcm) existe solo a través del plugin DICOM. Abrir una sin la capacidad requerida lanza:

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

Una extensión sin visor asignado genera:

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

Después de la resolución, la configuración se establece: tu objeto de configuración explícito si lo pasaste, de lo contrario la configuración predeterminada del formato del catálogo. DocOptions.Password se copia en la configuración para documentos protegidos.

Etapa 1b — Modo de redirección (DefaultRender = false)

La mayoría de las configuraciones por formato exponen una bandera DefaultRender. Selecciona entre dos rutas fundamentalmente diferentes:

• DefaultRender = true — el documento se renderiza de forma nativa, directamente a imágenes de página.
• DefaultRender = false — el documento se convierte primero a un PDF en memoria, el motor fuente se libera y un visor de PDF toma el control. El PDF generado incorpora texto real, por lo que la búsqueda de texto completo obtiene resaltados nativos precisos a nivel de píxel; el pipeline fuerza AllowSearch y AllowCopy activados para el PDF redirigido ya que la conversión es invisible para el usuario.

XPS y el valor predeterminado del catálogo para MHT utilizan la ruta de redirección. Una proyección a PDF puede proporcionar búsqueda nativa para formatos como HTML y Microsoft Project. Si el PDF resultante contiene imágenes sin capa de texto, el visor estándar no puede buscar esos píxeles.

Utiliza el modo de redirección cuando necesitas una proyección PDF con texto — a costa de una conversión inicial cuando se abre el documento.

Etapa 2 — El pipeline de imágenes de página

Las páginas renderizadas se procesan por solicitud a través de una secuencia fija:

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

• Marca de agua — aplicada según el estado de la licencia (licencia faltante, temporal o suscripción expirada, dominio inválido, versión incorrecta) y desde DocOptions.Watermark para tu propio texto personalizado. Una aplicación con licencia adecuada — o una licencia Temporal activa — sin marca de agua personalizada omite este paso.
• Rotar/voltear — el estado por página que el usuario establece en el widget (90°/180°/270°, volteos horizontal/vertical) se almacena en la sesión y se aplica en cada renderizado posterior de esa página.
• Escala — las miniaturas y niveles de zoom se producen escalando la página renderizada al tamaño objetivo solicitado; 0 significa servir en tamaño original.
• Quemado de anotaciones — las anotaciones guardadas se dibujan sobre el mapa de bits para que las exportaciones y las imágenes de página las muestren.
• Codificación — el resultado se codifica a PNG usando flujos de memoria agrupados y se escribe directamente a la respuesta HTTP.

Los errores dentro del middleware se devuelven como imágenes de error PNG (texto rojo sobre blanco) en lugar de páginas de error HTTP, de modo que el widget pueda mostrarlas en el área de la página.

Caché de páginas

BaseConfig.CachePages (predeterminado true) mantiene las imágenes de página renderizadas en memoria durante la vida de la sesión del documento, por lo que volver a visitar una página no la vuelve a renderizar. BaseConfig.ImageResolution (25–300 DPI, 0 = predeterminado del formato) es el control principal de calidad/memoria; el predeterminado de cada formato está documentado en su página de configuración.

DocOptions.ImageResolution está obsoleto y no controla la calidad del renderizado. Si estás trasladando una aplicación de la biblioteca anterior, mueve ese valor a la configuración del formato — el compilador señalará cada sitio de llamada.

Renderizado en un nodo vs. varios

Todo lo anterior describe un renderizado en un solo nodo bajo demanda para la sesión que abrió el documento. Un despliegue donde un nodo renderiza y publica todo el conjunto de artefactos, y otros nodos sirven esas páginas desde almacenamiento compartido, utiliza una ruta de lectura diferente — ver Despliegues Distribuidos.

Dónde ajustar qué