Pipeline 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 qué cambia realmente 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. Los visores personalizados primero. Cualquier cosa que hayas registrado con DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) prevalece sobre cualquier visor incorporado.
2. Visores de familia incorporados. El catálogo asigna cada extensión visible a una familia de visores — 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 complemento con licencia aporta un visor para la misma extensión, el visor del complemento reemplaza al incorporado. AddDoconut() valida los derechos de los complementos registrados al iniciar; el recurso de la fábrica al visor incorporado es una regla defensiva en tiempo de ejecución.
3. Formatos solo de complemento. Algunas extensiones no tienen ningún visor incorporado — DICOM (.dcm) existe solo a través del complemento 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 convertido 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; la pipeline obliga a que AllowSearch y AllowCopy estén 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.

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

Etapa 2 — La canal 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 correctamente licenciada — o una licencia Temporary 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 horizontales/verticales) se almacena en la sesión y se aplica en cada renderizado posterior de esa página.
• Escalar — las miniaturas y niveles de zoom se generan 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 en 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 (valor predeterminado true) mantiene las imágenes de página renderizadas en memoria durante la vida de la sesión del documento, de modo 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.

Dónde ajustar qué