Como o Visualizador Funciona

Doconut renderiza documentos como imagens paginadas servidas por meio de middleware ASP.NET Core. 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 três partes móveis

• Viewer — o serviço público que você injeta. Ele abre documentos e devolve tokens de sessão.
• A sessão do documento — um objeto do lado do servidor que mantém o documento carregado, indexado por um token em IMemoryCache.
• O middleware Doconut — adicionado por UseDoconut(); responde a todas as solicitações que o widget do navegador faz (pages, thumbnails, search, annotations, …), sempre autenticado pelo token.

Viewer é sem estado — por design

Viewer é selado, não mantém estado de documento por solicitação e deliberadamente não implementa IDisposable. As sessões vivem independentemente no gerenciador de sessões e são limpas por expiração do cache ou por um CloseDocument(token) explícito.

Injete‑o onde precisar:

app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

O que acontece dentro de OpenDocumentAsync

1. Portão de licença. Uma licença rejeitada ou expirada por versão (na lista negra, adulterada ou uma compilação fora da janela de atualização da licença) lança imediatamente uma LicenseException, com o motivo da rejeição como mensagem — a abertura nunca degrada silenciosamente para uma licença inválida (em oposição a ausente). Uma licença temporária ou de assinatura expirada por calendário é a exceção: ela não lança — degrada para uma marca d'água.
2. Criação da sessão. A fábrica do visualizador escolhe o visualizador de formato correto para a extensão do arquivo e carrega o documento (veja o Pipeline de Renderização). A sessão é armazenada em IMemoryCache sob um token GUID novo com expiração deslizante — DocOptions.TimeOut minutos, padrão 60. Cada solicitação de página reinicia o relógio.
3. Registro de segurança. Com UnsafeMode = false (o padrão), o token é vinculado à sessão ASP.NET do chamador: um marcador secure-{token} é gravado na sessão, de modo que somente a sessão do navegador que abriu o documento pode solicitar suas páginas.
4. O token é retornado. Ele é a credencial única para tudo que se segue.

As três sobrecargas diferem apenas na entrada: 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 determina a detecção do formato.

Como o widget obtém páginas

O widget cliente chama o middleware Doconut com o token na string de consulta. O que o middleware faz depende da solicitação:

Cada um desses caminhos valida primeiro:

• Sem token → o middleware retorna 404 (ou um banner de versão quando ShowDoconutInfo = true).
• Token desconhecido ou expirado → uma imagem de erro com Document session not found. Please re-open document.
• Middleware de sessão ausente (with UnsafeMode = false) → HTTP 500 com Session middleware not configured. Call UseSession() before UseDoconut().
• Token aberto por uma sessão de navegador diferente → uma imagem de erro com You Are Not Authorized To View This Page.

Fechando um documento

viewer.CloseDocument(token);

CloseDocument remove a sessão do cache (que descarta o mecanismo de documento subjacente e libera sua memória imediatamente), exclui o marcador secure-{token} e revoga a concessão de acesso. Chamá‑lo é opcional — a expiração deslizante faz a mesma limpeza automaticamente — mas para documentos grandes é a forma educada de liberar memória assim que o usuário terminar.

Conclusões

• Um documento aberto = uma sessão = um token. Tokens são por sessão de navegador, não URLs globais.
• O token expira em uma janela deslizante; um visualizador deixado inativo além de DocOptions.TimeOut precisa ser reaberto.
• Viewer pode ser injetado e compartilhado livremente; as sessões carregam todo o estado.