Visualizador de DOCX em ASP.NET Core: Pré-visualização de Arquivos Word

Para pré-visualizar um documento Word dentro de uma aplicação ASP.NET Core, use um SDK de visualizador de DOCX que renderiza o arquivo no servidor e exibe suas páginas no navegador. Doconut fornece esse fluxo de trabalho sem exigir o Microsoft Word no servidor. Seus usuários podem ler um contrato, proposta ou relatório dentro da sua aplicação em vez de abrir um programa de desktop separado.

Um relatório marfim com tabelas e gráficos se estende de uma pasta azul-marinho para uma moldura de vidro transparente

A questão útil é o que acontece quando você substitui o arquivo de demonstração pelos seus próprios documentos. Um contrato pode conter fontes personalizadas, cabeçalhos repetidos, tabelas largas e páginas de assinatura. Este guia mostra a etapa de abertura do documento para uma aplicação .NET 8 e as verificações que ajudam a avaliar o resultado.

Abrir um arquivo DOCX a partir de C#

Comece com o Doconut .NET 8 quick start para configurar os serviços, a sessão ASP.NET, o middleware de documentos, os recursos do visualizador e o widget do navegador. O endpoint a seguir estende essa aplicação configurada; ele não é uma aplicação completa e independente.

Coloque um documento de teste não sensível em App_Data/Sample.docx sob a raiz de conteúdo da aplicação. Adicione este endpoint antes de app.Run():

using Doconut;

app.MapPost("/api/preview-word", async (
    Viewer viewer,
    IWebHostEnvironment environment) =>
{
    var filePath = Path.Combine(
        environment.ContentRootPath, "App_Data", "Sample.docx");

    if (!File.Exists(filePath))
        return Results.NotFound();

    var token = await viewer.OpenDocumentAsync(filePath);
    return Results.Ok(new { token });
});

Mantenha a diretiva using com as outras importações no topo de Program.cs. O caminho fixo facilita a reprodução do exemplo e evita aceitar um caminho arbitrário do servidor proveniente do navegador.

A Viewer API reference documenta a sobrecarga de caminho de arquivo de OpenDocumentAsync. Ela abre o arquivo e devolve um token de sessão do documento. Na página onde o quick start já inicializou objViewer, abra a pré‑visualização com:

async function previewWordDocument() {
    const response = await fetch('/api/preview-word', {
        method: 'POST'
    });

    if (!response.ok) {
        throw new Error('The Word preview could not be opened.');
    }

    const { token } = await response.json();
    objViewer.View(token);
}

Chame essa função a partir da ação de pré‑visualização da sua página e exiba qualquer erro através da UI de erro já existente na aplicação. Mantenha a requisição na mesma origem da aplicação que o visualizador neste exemplo.

Mantenha o acesso ao documento sob controle da aplicação

Em um portal de clientes, substitua o exemplo fixo por um registro de documento selecionado pela sua aplicação. Verifique se o usuário atual pode visualizar esse registro antes de resolver sua localização de armazenamento e abri‑lo. Um nome de arquivo recebido do navegador não é uma decisão de autorização.

Armazene os originais protegidos fora da raiz pública da web. A pasta App_Data do exemplo é uma convenção de armazenamento, não um recurso de controle de acesso: não a exponha por meio de um mapeamento de arquivos estáticos. Mantenha a autenticação e as permissões de documentos na aplicação host.

O navegador recebe um token de visualização para a sessão do documento. Trate esse token como uma credencial, e não como uma URL permanente do documento. O quick start também cobre o fechamento de um documento quando o leitor sai ou abre outro arquivo.

Testar o layout do Word com arquivos representativos

Um DOCX vazio demonstra pouco sobre os documentos que seus clientes utilizam. Monte um pequeno conjunto de avaliação a partir dos modelos reais que sua aplicação precisa exibir, removendo informações sensíveis.

Documento de teste	O que inspecionar na pré-visualização
Contrato com cabeçalhos e rodapés	Conteúdo repetido, números de página e posicionamento da página de assinatura
Proposta usando uma fonte corporativa	Substituição de fonte, quebra de linha e larguras de cabeçalhos
Relatório com tabelas largas ou aninhadas	Larguras de coluna, divisão de linhas e texto cortado nos limites da página
Documento misturando seções retrato e paisagem	Dimensões da página e a transição entre seções
Manual com muitas imagens	Posicionamento de imagens, legendas e legibilidade ao ampliar

Compare o resultado renderizado com o documento fonte aprovado. Decida quais diferenças são relevantes para o seu fluxo de trabalho antes de avançar com a integração.

Doconut expõe configurações de renderização específicas do Word através de WordConfig. A format configuration reference inclui FontFolders para diretórios de fontes adicionais, configurações de tamanho de papel e AutoFitAllTables para ajuste de tabelas. Altere essas opções deliberadamente: fazer uma tabela ocupar toda a largura disponível também pode mudar o layout que você está tentando preservar.

Repita as verificações no host de implantação. Uma pré‑visualização que usa uma fonte instalada na máquina do desenvolvedor pode parecer diferente quando essa fonte está ausente no servidor. Use fontes que sua organização tem permissão para implantar.

Escolha visualização, edição e conversão separadamente

Uma pré‑visualização de DOCX resolve a etapa de leitura. Ela não transforma sua aplicação em um ambiente de autoria do Word.

Leitura: use o visualizador quando alguém precisar inspecionar um documento existente dentro de um caso, pedido ou registro de cliente.
Edição: se os usuários precisarem reescrever parágrafos e salvar um DOCX atualizado, avalie um fluxo de edição separadamente. Pré‑visualizar um arquivo não é evidência de suporte à edição no Word.
Conversão: se o requisito for um arquivo baixável em outro formato, avalie esse fluxo de exportação separadamente da exibição de páginas.

A Word viewer for .NET overview descreve o caminho de visualização da família Word da Doconut. Use-o para verificar o ajuste do produto, depois use seus próprios arquivos para avaliar o comportamento de renderização que importa para sua aplicação.

Avalie o visualizador com seu documento mais difícil primeiro

Comece com um documento que já gera solicitações de suporte: um contrato longo, um relatório pesado em tabelas ou um modelo com fontes incomuns. Verifique a pré‑visualização, navegue por várias páginas, reabra‑a em uma nova sessão e confirme que a aplicação circundante impõe as permissões corretas ao documento.

Baixar Doconut e execute o exemplo .NET 8 com esse arquivo. Uma avaliação bem‑sucedida deve demonstrar que os usuários podem ler os documentos que realmente recebem, com um layout revisado pela sua equipe e uma integração que sua aplicação pode manter.