Solução de Problemas – Documentação Doconut

Muitas falhas do System.Web não levantam exceção que você possa ver: a página responde com um 500 vazio, um ícone retorna 404, ou uma requisição nunca retorna. Esta página está organizada de acordo com o que você observa. Mensagens entre aspas são o texto literal que o Doconut produz.

Sintomas em um relance

O que você vê	Causa mais provável	Correção
Todas as solicitações respondem com um `500` vazio	Uma exceção em `Application_Start`: um plugin sem licença, uma opção inválida, uma configuração de farm incompleta — ou um redirecionamento de binding que nomeia uma versão que não está em `bin\`	Log de eventos do Windows, Aplicação, origem ASP.NET. Veja Falhas na inicialização
Algumas páginas MVC respondem com um `500` vazio	Razor compila as visualizações em tempo de execução: a fachada `netstandard` está ausente de `<compilation>`, ou a visualização usa C# mais recente que 5 (`?.`, `$"..."`, `nameof`)	Adicione a fachada (Instalação); mova a lógica da visualização para o controlador
Páginas exibem `â€”`, `â€¦` ou similar em vez de travessões e acentos	Arquivos de página sem marca de ordem de bytes são lidos com a página de código ANSI do servidor	`<globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />`
O console do navegador mostra `404` para `HEAD /DocImage.axd?...&page=1`	O manipulador está registrado sem o verbo `HEAD`	`verb="GET,HEAD,POST"` no manipulador
O documento é renderizado, mas os ícones da barra de ferramentas e o spinner de carregamento estão ausentes	`ResPath` aponta para a raiz de recursos, ou começa com `/`	`ResPath: 'doconut-res/images'`
Solicitações `/doconut-res/...` respondem `404`	O módulo de recurso não está registrado, `runAllManagedModulesForAllRequests` está desativado, ou o roteamento MVC captura o caminho	A entrada `<modules>`, e `routes.IgnoreRoute("doconut-res/{*pathInfo}")`
O visualizador relata `The viewer handler could not be reached (no response).`	`BasePath` começa com `/` (`'/myapp'` torna-se `//myapp/…`, outro host)	`BasePath: '/'` na raiz do site; `'myapp'` em um diretório virtual
O visualizador relata `Please make sure your middleware is configured.`	`DocImage.axd` respondeu `404`: o manipulador não está em `Web.config`, o roteamento MVC o capturou, ou `BasePath` aponta para outro lugar	A entrada `<handlers>`, `routes.IgnoreRoute("{resource}.axd/{*pathInfo}")`, e `BasePath`
Todas as páginas exibem `You Are Not Authorized To View This Page.`	O documento foi aberto em uma requisição sem estado de sessão, o estado de sessão está desativado, ou o cookie de sessão não chega a `DocImage.axd`	Ver Não autorizado
Uma conversão Web Forms nunca retorna	A página bloqueia em `ConvertAsync` — um deadlock	`Async="true"` + `RegisterAsyncTask` (Plugin Conversor)
Todas as páginas exibem uma marca d'água de avaliação	Nenhuma licença foi encontrada — não está em `<site root>\wwwroot`	Configuração de Licença
Um widget carrega, mas sua primeira ação responde `404`	O widget não está habilitado, ou seu `basePath` não está `'/DocImage.axd'`	`options.Add…Widget()`, e `basePath: '/DocImage.axd'`
O primeiro documento após o site iniciar ou reciclar leva um minuto ou mais; os posteriores são rápidos	Os motores de documento carregam na primeira abertura, e o antivírus em tempo real os escaneia enquanto carregam	Aqueça o site e mantenha o pool em execução — veja O primeiro documento após uma inicialização
Um upload grande exibe uma página de erro do IIS	O upload excede `maxRequestLength` (KB) ou `maxAllowedContentLength` (bytes)	Aumente ambos acima do seu maior arquivo ou limite de widget

Falhas na inicialização

Uma exceção lançada em Application_Start não chega ao navegador: toda requisição responde com um 500 vazio, e o log do IIS não mostra nada útil. A exceção está no log de eventos do Windows (Visualizador de Eventos → Logs do Windows → Aplicação, origem ASP.NET). As mais comuns:

Um plugin sem sua licença:

text

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

O Doconut.Viewer.<Capability>.lic do plugin deve estar em wwwroot, ao lado de Doconut.Viewer.lic. Uma licença ausente e um arquivo legado TRIAL não concedem capacidades ao plugin.

Opções inválidas:

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.

Um assembly que não pode ser carregado. ASP.NET carrega todo assembly em bin\ quando a aplicação inicia, então um redirecionamento de binding em Web.config que nomeia uma versão ausente de bin\ interrompe todo o site. Copie os redirecionamentos gerados pelo NuGet (para um projeto estilo SDK, de bin\<YourApp>.dll.config) em vez de editá-los manualmente, e copie-os novamente após atualizações de pacotes.

Você não está autorizado a visualizar esta página.

A página foi recusada porque a sessão ASP.NET solicitante nunca recebeu o documento. Verifique, na ordem:

A abertura foi executada com estado de sessão. Controladores MVC e páginas Web Forms o possuem. Um IHttpHandler personalizado que abre documentos deve implementar System.Web.SessionState.IRequiresSessionState, caso contrário não tem sessão para conceder.
O estado de sessão está ativado. <sessionState mode="Off" /> recusa todas as páginas.
O cookie chega ao manipulador. As solicitações de mesma origem do widget transportam ASP.NET_SessionId; um script, uma chamada servidor‑para‑servidor ou uma página de origem cruzada sem cookies não o faz.
Fazenda web: a abertura vinculou o navegador (DocOptions.BrowserId) e a página passa o ticket (objViewer.View(token, access)); cada nó usa a mesma chave de assinatura.

A recusa é uma imagem servida com o status 200, cerca de 2 KB. Um monitor que verifica apenas códigos de status a conta como uma página.

Sessão de documento não encontrada. Por favor, reabra o documento.

O token expirou (janela deslizante, DocOptions.TimeOut, padrão 60 minutos), o documento foi fechado ou — em um único servidor — o pool de aplicativos foi reciclado. A reciclagem ocorre conforme agendamento, a cada edição Web.config, e após o tempo limite de inatividade do pool (20 minutos por padrão no IIS). Abra o documento novamente para obter um novo token.

Falha ao abrir um documento

LicenseException com um motivo de rejeição — o arquivo de licença foi encontrado, mas rejeitado (assinatura inválida, adulteração, lista negra ou uma compilação fora da janela de versão da licença). A abertura é bloqueada em vez de receber marca d'água.

LicenseException:

text

This document type requires the 'Dicom' plugin license.

A extensão é tratada apenas por um plugin (aqui DICOM) cuja capacidade não foi concedida.

FormatNotSupportedException — nenhum visualizador (integrado, plugin ou personalizado) reconhece a extensão. DoconutOptions.RegisterViewer pode adicionar um para seus próprios formatos.

InvalidDataException — o conteúdo está corrompido ou não corresponde à sua extensão (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>().

DocumentConverter foi resolvido sem registrar o plugin Converter.

A saída parece errada

As páginas carregam uma marca d'água — nenhuma licença foi encontrada, ou ela expirou ou não cobre esta versão. No IIS, a licença deve estar em wwwroot sob a raiz do site (AppContext.BaseDirectory\wwwroot), não em bin\. Verifique IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, License.RejectionMessage).

Documentos legados renderizam texto embaralhado — registre as codificações de página de código uma única vez, na inicialização:

csharp

// Global.asax.cs, Application_Start - antes de DoconutHost.Initialize.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Fontes erradas ou substituídas — o servidor não possui as fontes do documento. Um Windows Server sem Office tem muito menos fontes que uma máquina de desenvolvimento. Instale as fontes, ou aponte FontFolders (em WordConfig e 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 Annotations.

Recurso funcionava na avaliação, mas está silencioso em produção

Uma licença Temporária ativa concede todas as capacidades; sua licença comprada concede apenas o que você adquiriu. Sem uma capacidade, seus arquivos de Busca ou Anotação não são gerados, e um plugin registrado impede o site na inicialização. Compare IsCapabilityGranted(...) com cada recurso que você usa antes de implantar.

Busca não encontra nada (ou muito pouco)

Para PDF, AllowSearch não foi habilitado quando o documento foi aberto — o padrão é false. Word, Excel e PowerPoint expõem a mesma opção.
O conteúdo é escaneado ou apenas imagem, portanto não há camada de texto para corresponder.
HTML e Microsoft Project (MPP) não são pesquisáveis por padrão: configure DefaultRender = false para que eles sejam renderizados por meio de uma projeção PDF com texto.
objViewer.CanSearch() está false após a inicialização: o formato resolvido não tem caminho de busca. Isso é separado da licença de Busca; verifique ambos.
A página lê o valor de retorno de objViewer.Search(...) — a contagem chega no terceiro argumento, um callback.

Ainda preso?

Reproduza o problema com a configuração mínima a partir de Início rápido. Se ele for reproduzido lá, entre em contato com o suporte com o documento, seu Global.asax.cs, as partes Doconut de Web.config, e a entrada do log de eventos do Windows, se houver.