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 ao DocImage.axd). Conhecer ambas explica por que um formato é renderizado da maneira 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.
3. Formatos apenas de plugin. Algumas extensões não têm visualizador incorporado — DICOM (.dcm, .ima) existe apenas através do plugin DICOM. Abrir um sem a capacidade necessária gera:

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

Uma extensão que nenhum visualizador reconhece gera FormatNotSupportedException.

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, diretamente para imagens de página.
• DefaultRender = false — o documento é primeiro convertido para PDF na memória, o engine de origem é liberado, e um visualizador de PDF assume. O PDF gerado contém texto real, portanto a pesquisa de texto completo obtém realces nativos exatos; o pipeline ativa AllowSearch e AllowCopy para o PDF redirecionado, já que a conversão é invisível ao usuário.

XPS e MHT, por padrão, usam o caminho de redirecionamento. Uma projeção em PDF fornece pesquisa nativa para formatos como HTML e Microsoft Project. Se o PDF resultante contiver imagens sem camada de texto, esses pixels não podem ser pesquisados.

Use o modo de redirecionamento quando precisar de uma projeção pesquisável e com texto — ao custo de uma conversão inicial quando o documento é aberto.

Etapa 2 — O pipeline de imagem de página

Cada solicitação de página ao DocImage.axd executa 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 (sem licença, licença temporária ou de assinatura expirada, domínio inválido, compilação fora das versões da licença) e de DocOptions.Watermark para seu próprio texto. Um site licenciado 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 e vertical) é armazenado na sessão e aplicado a 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 solicitado.
• Gravação de anotações — anotações salvas são desenhadas sobre o bitmap, de modo que exportações e imagens de página as exibam.
• Codificação — o resultado é codificado como PNG e escrito diretamente na resposta.

Erros dentro do manipulador são retornados como imagens de erro PNG (texto vermelho sobre branco) com status 200, em vez de páginas de erro HTTP, para que o widget possa exibi-los 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 renderiza novamente. BaseConfig.ImageResolution (25–300 DPI, 0 = o padrão do formato) é o principal controle de qualidade e memória; o padrão de cada formato está listado em Configurações de Formato.

Em um único nó, sessões e páginas em cache vivem na memória do processo de trabalho. Uma reciclagem do pool de aplicativos — programada, ou acionada por uma edição do Web.config ou por timeout ocioso — descarta todas as sessões de documentos abertas, e o widget então exibe Document session not found. Please re-open document. No modo distribuído (veja Sessões e Segurança), uma sessão é reconstruída a partir do armazenamento compartilhado.

Onde ajustar o quê