Pipeline de Renderização

Entre OpenDocumentAsync e o PNG que chega ao navegador há duas etapas distintas: resolução do visualizador (qual engine carrega o documento, decidido uma vez por abertura) e processamento de página (o que acontece com cada imagem de página a cada solicitação). Conhecer ambas explica por que um formato é renderizado da forma que é — e o que DefaultRender realmente altera.

Etapa 1 — Resolvendo o visualizador de formato

A fábrica mapeia a extensão do arquivo para um visualizador através do catálogo de formatos, com três níveis de precedência:

1. Visualizadores personalizados primeiro. Qualquer coisa que você registrou com DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) tem prioridade sobre todos os incorporados.
2. Visualizadores de família incorporados. O catálogo mapeia cada extensão visualizável para uma família de visualizadores — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — cada um com seu próprio adaptador de engine. Se um plugin licenciado contribuir com um visualizador para a mesma extensão, o visualizador do plugin substitui o incorporado. AddDoconut() valida as permissões de plugins registrados na inicialização; o fallback da fábrica para o visualizador incorporado é uma regra defensiva em tempo de execução.
3. Formatos apenas de plugin. Algumas extensões não têm visualizador incorporado — DICOM (.dcm) existe apenas através do plugin DICOM. Abrir um sem a capacidade requerida lança:

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

Uma extensão sem visualizador associado gera:

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

Após a resolução, a configuração é definida: seu objeto de configuração explícito se você o passou, caso contrário a configuração padrão do formato do catálogo. DocOptions.Password é copiado para a configuração de documentos protegidos.

Etapa 1b — Modo de redirecionamento (DefaultRender = false)

A maioria das configurações por formato expõe uma flag DefaultRender. Ela seleciona entre dois caminhos fundamentalmente diferentes:

• DefaultRender = true — o documento é renderizado nativamente, direto para imagens de página.
• DefaultRender = false — o documento é primeiro convertido para um PDF na memória, o engine de origem é liberado, e um visualizador de PDF assume. O PDF gerado incorpora texto real, portanto a pesquisa de texto completo obtém realces nativos precisos ao pixel; o pipeline força AllowSearch e AllowCopy ativados para o PDF redirecionado, já que a conversão é invisível ao usuário.

XPS e o padrão do catálogo para MHT utilizam o caminho de redirecionamento. Uma projeção em PDF pode fornecer pesquisa nativa para formatos como HTML e Microsoft Project. Se o PDF resultante contiver imagens sem camada de texto, o visualizador padrão não pode pesquisar esses pixels.

Use o modo de redirecionamento quando precisar de uma projeção PDF contendo texto — ao custo de uma conversão inicial quando o documento é aberto.

Etapa 2 — O pipeline de imagem de página

As páginas renderizadas são processadas por solicitação através de uma sequência fixa:

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

• Marca d'água — aplicada a partir do estado da licença (licença ausente, temporária ou de assinatura expirada, domínio inválido, versão incorreta) e de DocOptions.Watermark para seu próprio texto personalizado. Um aplicativo devidamente licenciado — ou uma licença Temporária ativa — sem marca d'água personalizada pula esta etapa.
• Rotacionar/inverter — o estado por página que o usuário define no widget (90°/180°/270°, inversões horizontal/vertical) é armazenado na sessão e aplicado em cada renderização subsequente daquela página.
• Escala — miniaturas e níveis de zoom são produzidos escalando a página renderizada para o tamanho alvo solicitado; 0 significa servir no tamanho original.
• Gravação de anotação — anotações salvas são desenhadas sobre o bitmap para que exportações e imagens de página as exibam.
• Codificação — o resultado é codificado em PNG usando streams de memória em pool e escrito diretamente na resposta HTTP.

Erros dentro do middleware são retornados como imagens de erro PNG (texto vermelho sobre branco) ao invés de páginas de erro HTTP, permitindo que o widget as exiba na área da página.

Cache de página

BaseConfig.CachePages (padrão true) mantém as imagens de página renderizadas na memória durante a vida da sessão do documento, de modo que revisitar uma página não a re-renderiza. BaseConfig.ImageResolution (25–300 DPI, 0 = padrão do formato) é o principal controle de qualidade/memória; o padrão de cada formato está documentado em sua página de configuração.

Onde ajustar o que