Como o Visualizador Funciona

Doconut renderiza documentos como imagens paginadas, servidas por um manipulador HTTP que seu Web.config registra. Entender o ciclo de vida — abrir, token, solicitações de página, fechar — explica quase todo comportamento que você observará, incluindo as mensagens de erro.

As partes móveis

• Viewer — o serviço público que você resolve a partir de DoconutHost.Services. Ele abre documentos e retorna tokens de sessão.
• A sessão do documento — um objeto do lado do servidor que mantém o documento carregado, mantido na memória sob seu token.
• DocImage.axd — o Doconut.DocImageHandler declarado em Web.config. Ele responde a cada solicitação que o widget do navegador faz (páginas, miniaturas, pesquisa, anotações, …), sempre identificado pelo token.
• /doconut-res/* — o Doconut.DoconutResourceModule, que serve os próprios scripts, estilos e ícones do widget.

Viewer é sem estado — por design

Viewer não mantém estado de documento por solicitação e não implementa IDisposable. As sessões vivem independentemente dele e são limpas por expiração ou por um CloseDocument(token) explícito. System.Web não tem injeção de construtor, então resolva‑o onde precisar — tipicamente em uma ação de controlador:

// POST /ViewerApi/Open?fileName=Sample.pdf
[HttpPost]
public async Task<ActionResult> Open(string fileName)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    var path   = Server.MapPath("~/files/" + Path.GetFileName(fileName));

    var token = await viewer.OpenDocumentAsync(path);
    return Content(token, "text/plain");
}

O que acontece dentro de OpenDocumentAsync

1. Portão de licença. Uma licença rejeitada (alterada, na lista negra, ou uma compilação fora da janela de atualização da licença) lança LicenseException imediatamente, com a razão como mensagem. A abertura nunca degrada silenciosamente para uma licença inválida; uma licença ausente apenas adiciona marca d'água.
2. Criação da sessão. A fábrica do visualizador escolhe o visualizador de formato para a extensão do arquivo e carrega o documento (veja Pipeline de Renderização). A sessão é armazenada na memória sob um novo token aleatório com uma expiração deslizante de DocOptions.TimeOut minutos (padrão 60). Cada solicitação de página reinicia o relógio.
3. Concessão de acesso. Com UnsafeMode = false (o padrão), o token é vinculado à sessão ASP.NET da solicitação que o abriu: uma entrada secure-{token} é escrita nessa sessão. A abertura deve, portanto, ser executada em uma solicitação com estado de sessão — veja Sessões e Segurança.
4. O token é retornado. Ele é o único identificador que o navegador precisa para tudo que se segue.

As sobrecargas assíncronas aceitam um caminho de arquivo, um caminho de arquivo mais uma configuração por formato (PdfConfig, WordConfig, …), ou um Stream mais um FileInfo cuja extensão seleciona o formato. Para código‑behind de Web Forms que não usa páginas assíncronas, OpenDocument oferece as mesmas três entradas de forma síncrona (um caminho, um fluxo com um nome de arquivo, ou um array de bytes com um nome de arquivo).

Como o widget obtém páginas

O widget chama DocImage.axd com o token na string de consulta. O que o manipulador faz depende da solicitação:

Cada solicitação é verificada primeiro:

• Sem token → 404, ou um banner de versão quando ShowDoconutInfo = true.
• Token não concedido a esta sessão ASP.NET → uma imagem de erro contendo You Are Not Authorized To View This Page.
• Token desconhecido ou expirado → uma imagem de erro contendo Document session not found. Please re-open document.

As imagens de erro são PNGs comuns enviadas com status 200, para que o widget possa exibí‑las onde a página estaria. Uma verificação de monitoramento que olha apenas o código de status as reportará como páginas servidas; uma página real tem de dezenas a centenas de kilobytes, enquanto uma imagem de erro tem cerca de 2 KB.

Fechando um documento

viewer.CloseDocument(token);

CloseDocument remove a sessão (liberando o motor de documento e sua memória imediatamente), remove a entrada secure-{token} da sessão ASP.NET da solicitação atual, e revoga o token. É opcional — a expiração deslizante faz a mesma limpeza — mas para documentos grandes libera memória no momento em que o usuário termina. Do navegador, objViewer.Close(true) envia a solicitação de fechamento equivalente para DocImage.axd.

Principais pontos

• Um documento aberto = uma sessão = um token, concedido à sessão ASP.NET que o abriu.
• O token expira em uma janela deslizante; um visualizador deixado inativo além de DocOptions.TimeOut precisa ser reaberto.
• Viewer pode ser resolvido e compartilhado livremente; as sessões carregam todo o estado.