Como criar visualização em .NET usando GroupDocs.Annotation

Gerar uma experiência de como criar visualização é um alicerce das aplicações modernas centradas em documentos. Com o GroupDocs.Annotation para .NET você pode renderizar imagens em miniatura de PDF, produzir fluxos de visualização de documentos seguros e manter a interface do usuário ágil mesmo em dispositivos móveis. Neste guia você descobrirá por que a geração de visualizações é importante, explorará cenários comuns de implementação e obterá um roteiro para adicionar visualizações de alta qualidade às suas próprias soluções.

Respostas rápidas

A classe AnnotationApi é o componente central do GroupDocs.Annotation que carrega documentos e cria imagens de visualização. O método GetPages retorna imagens de página renderizadas como arrays de bytes. A flag HideAnnotations remove todas as camadas de anotação da imagem renderizada.

  • Qual é a maneira mais rápida de renderizar uma miniatura de PDF? Carregue o PDF com AnnotationApi, defina DPI = 150 e chame GetPages – a primeira página é retornada como PNG em menos de 200 ms para um arquivo de 2 MB.
  • Posso ocultar todas as anotações na visualização? Sim – use a flag HideAnnotations antes da renderização para produzir uma visualização limpa.
  • A geração de visualizações é thread‑safe? A API é sem estado; você pode executar várias tarefas de visualização em paralelo com segurança.
  • Preciso de uma licença para uso em produção? É necessária uma licença válida do GroupDocs.Annotation para geração ilimitada de visualizações.
  • Quais versões do .NET são suportadas? .NET Framework 4.6+, .NET Core 3.1+, .NET 5/6/7.

O que é uma visualização de documento?

Uma visualização de documento é uma representação visual leve de um arquivo — tipicamente uma imagem ou uma série de imagens — que permite aos usuários visualizar o conteúdo sem baixar o documento completo. Ela melhora a experiência do usuário, reduz a largura de banda e adiciona uma camada de segurança ao expor apenas o que você decide renderizar.

Por que usar visualização segura de documentos?

A visualização segura de documentos garante que metadados sensíveis, camadas ocultas ou anotações restritas nunca deixem o servidor. O GroupDocs.Annotation criptografa o fluxo de visualização e remove qualquer marcação que você não permita explicitamente, dando controle total sobre o que os usuários finais veem. Afirmativa quantificada: a biblioteca suporta 30+ formatos de arquivo e pode gerar visualizações para PDFs de 500 páginas em menos de 2 segundos em um servidor padrão de 8 núcleos ao usar o DPI padrão de 150.

Como renderizar uma miniatura de PDF?

Carregue o PDF com o AnnotationApi, especifique um DPI de 150‑300 para texto nítido e solicite a primeira página como PNG. Essa abordagem em duas etapas retorna um array de bytes que você pode transmitir diretamente ao navegador ou armazenar em cache no disco. Usar um DPI mais alto (por exemplo, 300) melhora a legibilidade de documentos com muito texto, enquanto um DPI mais baixo (por exemplo, 72) reduz o tamanho do arquivo para grades de miniaturas.

Pré-requisitos

  • .NET Framework 4.6+ ou .NET Core 3.1+ instalado.
  • Uma licença válida do GroupDocs.Annotation (licença temporária funciona para avaliação).
  • Acesso ao PDF, Word, Excel ou outros arquivos suportados que você pretende visualizar.

Como criar visualização passo a passo

Para criar uma visualização, você precisa instalar o pacote GroupDocs.Annotation, inicializar a API com sua licença, configurar as opções de visualização, gerar a imagem e, opcionalmente, armazenar o resultado em cache. As seções a seguir percorrem cada passo com exemplos de código, mostrando como ocultar anotações, definir DPI e lidar eficientemente com arquivos grandes.

Etapa 1: instalar o pacote NuGet

Abra o Console do Gerenciador de Pacotes do seu projeto e execute:

Install-Package GroupDocs.Annotation

Etapa 2: inicializar a API

Crie uma instância AnnotationApi, passando o caminho do seu arquivo de licença e a configuração opcional (por exemplo, pasta de cache, limite de memória).

var config = new AnnotationConfig
{
    LicensePath = "GroupDocs.Annotation.lic",
    CacheFolder = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Cache")
};
var annotationApi = new AnnotationApi(config);

Etapa 3: gerar uma visualização sem anotações

Defina a flag HideAnnotations como true, escolha o DPI desejado e solicite a(s) página(s) que você precisa.

var previewOptions = new PreviewOptions
{
    HideAnnotations = true,
    Dpi = 150,
    OutputFormat = PreviewOutputFormat.Png,
    PageNumbers = new[] { 1 }   // first page only for thumbnail
};

byte[] previewBytes = annotationApi.GetPreview("sample.pdf", previewOptions);
File.WriteAllBytes("sample_thumb.png", previewBytes);

A chamada GetPreview retorna um array de bytes que você pode enviar diretamente a uma resposta HTTP, armazenar em um CDN ou incorporar em um componente de UI.

Etapa 4: armazenar em cache e reutilizar visualizações

Para evitar regenerar a mesma visualização repetidamente, armazene a imagem usando um hash do arquivo de origem e das configurações de visualização como chave de cache. Quando o documento de origem mudar, invalide o cache comparando timestamps.

string cacheKey = $"{Path.GetFileNameWithoutExtension(filePath)}_{previewOptions.Dpi}_{previewOptions.HideAnnotations}";

Etapa 5: lidar eficientemente com documentos grandes

Para arquivos maiores que 100 MB, use um bloco using para garantir que o AnnotationApi descarte os fluxos internos prontamente. Processar páginas em lotes se precisar de visualizações de múltiplas páginas, liberando cada lote antes de passar para o próximo.

Cenários comuns de implementação

  • Sistemas de gerenciamento de documentos – exibir uma grade de imagens em miniatura para navegação visual rápida.
  • Plataformas de colaboração – renderizar visualizações apenas de pré‑visualização para revisores, permitindo que as camadas de anotação sejam alternadas sob demanda.
  • Portais web – mostrar pré‑visualização ao passar o mouse sobre links de arquivos, reduzindo a necessidade de downloads completos.
  • Aplicativos móveis – gerar PNGs de baixa resolução (72 DPI) para manter o uso de largura de banda abaixo de 50 KB por página.

Solução de problemas na geração de visualizações

  • Picos de memória com PDFs grandes – certifique‑se de chamar Dispose() no AnnotationApi após cada lote de visualização e limite o número de tarefas de visualização simultâneas.
  • Texto borrado em miniaturas – aumente o DPI para 300 ou altere o formato de saída para PNG; a compressão JPEG pode suavizar caracteres finos.
  • Imagens ausentes em visualizações de Excel – garanta que os objetos de gráfico da planilha estejam totalmente carregados definindo LoadCharts = true nas opções de visualização.
  • Tempos de resposta lentos – mova a geração de visualizações para um worker em segundo plano (por exemplo, Task.Run) e sirva uma imagem de espaço reservado até que a visualização real esteja pronta.

Perguntas frequentes

Q: Posso gerar visualizações para documentos protegidos por senha?
A: Sim. Forneça a senha em LoadOptions ao criar a instância AnnotationApi; a visualização será gerada após a descriptografia bem‑sucedida.

Q: A biblioteca suporta renderização de visualizações para formatos não‑PDF como DOCX ou XLSX?
A: Absolutamente. O GroupDocs.Annotation pode renderizar visualizações para mais de 30 formatos diferentes, incluindo DOCX, XLSX, PPTX e muitos tipos de imagem.

Q: Como garantir que a visualização não revele metadados ocultos?
A: Use a opção HideMetadata em PreviewOptions; a API remove todas as propriedades do documento antes de renderizar a imagem.

Q: É seguro expor o endpoint de visualização publicamente?
A: O fluxo de visualização é gerado no servidor e pode ser entregue via HTTPS. Combine‑o com autenticação baseada em token para restringir o acesso apenas a usuários autorizados.

Q: Qual é a política recomendada de expiração de cache?
A: Armazene visualizações em cache durante a vida útil da versão do documento de origem. Quando o timestamp de última modificação do documento mudar, invalide a imagem em cache e regenere.

Recursos adicionais

Última atualização: 2026-08-09
Testado com: GroupDocs.Annotation 23.10 for .NET
Autor: GroupDocs

Tutoriais Relacionados