Resolução de Problemas

Diagnosticar erros comuns

Cada mensagem abaixo é o texto literal que o Doconut produz, organizado por sintoma. Encontre seu erro, aplique a correção.

O visualizador não mostra nada

Área do visualizador vazia, console do navegador cheio de 404s para /doconut-res/...
UseDoconutResources() está ausente, ou colocado após UseDoconut(). Ele deve ser o primeiro no pipeline.

O visualizador relata The viewer handler could not be reached (no response).
A solicitação nunca recebeu uma resposta. Uma causa comum é um BasePath que começa com /: '/doconut' torna-se //doconut/DocImage.axd, uma solicitação para outro host. Escreva sem a barra inicial (BasePath: 'doconut').

O visualizador relata Please make sure your middleware is configured.
O ponto final da página respondeu 404: UseDoconut() não está montado onde o BasePath do cliente aponta. Com app.Map("/doconut", branch => branch.UseDoconut()), o cliente usa BasePath: 'doconut'.

HTTP 500 com:

text
Session middleware not configured. Call UseSession() before UseDoconut().

A segurança de token do Doconut (ativada por padrão) requer estado de sessão do ASP.NET. Adicione builder.Services.AddSession() e app.UseSession() antes do ramo de middleware do Doconut. O estado de sessão também precisa de um cache: em um aplicativo minimal-API adicione builder.Services.AddDistributedMemoryCache(), ou o aplicativo para na inicialização com Unable to resolve service for type 'IDistributedCache' (aplicativos MVC e Razor Pages já registram um).

Uma imagem de erro na área da página exibindo:

text
You Are Not Authorized To View This Page.

O token foi aberto por uma sessão de navegador diferente. Causas típicas: o cookie de sessão não está chegando às solicitações da página (configuração cross-origin, política SameSite, um cliente API sem jar de cookies), ou o aplicativo reiniciou (novas chaves de sessão). Esta é a camada de segurança funcionando como projetado — veja Conceitos Principais → Sessões & Segurança. A recusa é uma imagem servida com status 200, então um monitor que verifica apenas códigos de status a conta como uma página.

Uma imagem de erro exibindo:

text
Document session not found. Please re-open document.

O token expirou (janela deslizante, padrão 60 minutos — DocOptions.TimeOut) ou a sessão foi encerrada. Reabra o documento para obter um token novo.

O servidor está ok, mas a página se comporta de forma errada — sem erro em nenhum lugar

Estes são os modos de falha a suspeitar primeiro ao avançar uma aplicação. Todos os três deixam o servidor funcionando perfeitamente, renderizam o documento corretamente e não reportam nada no console do navegador.

Um spinner ativo que nunca para. Seus callbacks do visualizador são declarados como funções globais nomeadas após o id do contêiner — ctlDoc_OnViewerReady() e afins. O visualizador anterior procurava esses nomes; este não. O manipulador que ocultaria o spinner simplesmente nunca é executado. Passe as funções como opções em vez disso:

javascript
function ctlDoc_OnViewerBusy() { /* mostre seu indicador de ocupação */ }
function ctlDoc_OnViewerReady() { /* oculte-o */ }
function ctlDoc_Copy(text) { /* use o texto copiado */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* relate o progresso */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... suas opções existentes ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

O documento por trás do spinner está ok. A lista completa de opções está em ConfiguraçõesDoVisualizador.

Ícones ou chrome do visualizador ausentes, páginas corretas de outra forma. ResPath está vazio ou aponta para a raiz da aplicação — correto na biblioteca anterior, errado aqui. Deve nomear o prefixo que UseDoconutResources() monta:

javascript
ResPath: 'doconut-res/images'   // ou '<your ResourcesPath>/images'

Ladrilhos quebrados em páginas posteriores ao servir de armazenamento compartilhado. Páginas que ainda estão sendo gravadas respondem 202 Accepted. Um cliente sem retryOn409: true trata isso como uma imagem falha. Veja Implantações Distribuídas.

Falha ao abrir um documento

LicenseException com uma mensagem de rejeição — o arquivo de licença foi encontrado, mas rejeitado (assinatura inválida, adulterado, na lista negra ou uma compilação fora da janela de versão/atualização da licença). Esse estado impede a abertura (falha rápida) em vez de degradar para uma marca d'água; leia License.RejectionMessage para saber o motivo.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

A extensão é tratada apenas por um plugin (aqui: DICOM). O plugin está registrado, mas nenhuma licença concede sua capacidade mais — tipicamente uma licença Temporária que expirou após o início do aplicativo. Instale uma licença que a conceda e verifique IsCapabilityGranted(LicenseCapability.Dicom) em IDoconutLicenseService. Uma concessão não‑temporária ausente ou insuficiente normalmente falha antes, durante AddDoconut().

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

Nenhum visualizador — interno, plugin ou personalizado — reconhece essa extensão. Verifique a lista de formatos suportados; para seus próprios formatos, DoconutOptions.RegisterViewer pode adicionar um.

InvalidDataException — o conteúdo do arquivo está corrompido ou não corresponde à sua extensão (por exemplo, um arquivo renomeado). Valide os uploads antes de abrir.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Você resolveu DocumentConverter sem registrar o plugin Conversor.

Falha na inicialização

InvalidOperationException mencionando um plugin registrado via AddPlugin — a licença não‑temporária atual não concede essa capacidade ao plugin. Remova o registro ou instale uma licença que a conceda. Uma licença ausente e um arquivo legado TRIAL não concedem capacidades de plugin.

ArgumentException de AddDoconut():

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Validação de opções de falha rápida — corrija o caminho problemático.

Erros de compilação / dependência

O pacote não será instalado de forma alguma — Doconut.NETStandard tem como alvo netstandard2.1, então o NuGet recusa um projeto .NET Framework. Este não é um erro de restauração resolvível: .NET Framework não pode consumir netstandard2.1. Use o pacote Doconut.NETFramework em vez disso.

Erro de compilador CS1705, ou em tempo de execução ao abrir um documento:

text
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

Seu projeto fixou System.Text.Json ou System.Text.Encodings.Web abaixo das dependências 9.0.x declaradas por Doconut.NETStandard. Remova a redução de versão e deixe o NuGet restaurar o grafo de pacotes (System.Text.Json 9.0.0 e System.Text.Encodings.Web 9.0.0 conforme declarado pelo pacote).

Uma série de erros de compilação imediatamente após atualizar o pacote — isso é esperado. 26.8.0 tem uma superfície de API diferente de 26.7.0, não é uma atualização compatível. A maioria dos erros são as linhas using que foram movidas para o namespace raiz Doconut; trabalhe através delas usando Migrar para .NET Standard 2.1 em vez de corrigir uma a uma.

TypeInitializationException no primeiro arquivo de apresentação:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

O mecanismo de apresentação exige rigidamente System.Drawing.Common 6.0.0 (declarado pelo pacote). Não remova ou sobrescreva essa dependência — toda abertura de PPT/PPTX/PPS/POT/ODP falha sem ela.

A saída parece errada

As páginas exibem uma marca d'água — o aplicativo está em estado de avaliação: nenhum arquivo de licença encontrado, uma licença Temporária expirada ou um domínio inválido. Sob uma licença Temporária ativa, apenas a saída do plugin recebe marca d'água. Uma compilação lançada após a data de assinatura de uma licença paga não tem marca d'água: ao abrir lança LicenseException. Inspecione IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — a referência IDoconutLicenseService da página de Licenciamento mostra um endpoint pronto.

Documentos legados exibem texto corrompido — as codificações de página de código não são carregadas por padrão. Adicione uma única vez na inicialização:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Fontes erradas ou substituídas — o servidor não possui as fontes do documento. Instale-as ou aponte FontFolders (em WordConfig/PptConfig) para uma pasta que as contenha.

Uma anotação de imagem aparece no visualizador, mas a exportação tem uma caixa "Imagem bloqueada" — o host da imagem tem um endereço privado ou de loopback, que o servidor se recusa a buscar. Veja Anotações.

Recurso funcionava na avaliação, silencioso em produção

A clássica surpresa ao entrar em produção: uma licença Temporária ativa concede todas as funcionalidades; sua licença adquirida concede apenas o que você comprou. Pacotes de busca e anotação podem desaparecer quando suas funcionalidades estão ausentes. Conversor registrado ou plugins DICOM com uma licença não temporária insuficiente falham durante AddDoconut(). Compare IsCapabilityGranted(...) com cada recurso que você habilita antes da implantação.

Busca não encontra nada (ou muito pouco)

  • Para um PDF direto, AllowSearch não foi habilitado no momento da abertura. Word, Excel e PowerPoint expõem a mesma opção através de seus PdfConfig aninhados.
  • O conteúdo é escaneado/apenas imagem, portanto a Busca normal não tem camada de texto para corresponder. Use uma fonte que contenha texto ou uma projeção de PDF que preserve o texto.
  • HTML e MS Project (MPP) não são pesquisáveis em suas configurações padrão — configure DefaultRender = false para que eles sejam renderizados via uma projeção de PDF com camada de texto nativa. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB e MHT pesquisam em suas configurações padrão de catálogo.
  • objViewer.CanSearch() está false após a inicialização — o formato resolvido não tem caminho de busca padrão. Este veredicto é separado da licença de Busca; verifique ambos.
  • A página lê o valor de retorno de objViewer.Search(...) — a contagem chega em seu terceiro argumento, um callback.

Ainda preso?

Isole o problema usando o aplicativo Quick Start mínimo; se ele se reproduzir lá, entre em contato com o suporte com o documento, seu Program.cs e a saída de diagnóstico da licença.

Esta página foi útil?