Como o Visualizador Funciona
O ciclo de vida da solicitação de documentos
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 em movimento
Viewer— o serviço público que você resolve a partir deDoconutHost.Services. 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, guardado na memória sob seu token.
DocImage.axd— oDoconut.DocImageHandlerdeclarado emWeb.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/*— oDoconut.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. O System.Web não possui injeção via construtor, portanto 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
- 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
LicenseExceptionimediatamente, com a razão como mensagem. A abertura nunca degrada silenciosamente para uma licença inválida; uma licença ausente apenas adiciona marcas d'água. - 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.TimeOutminutos (padrão 60). Cada solicitação de página reinicia o relógio. - Concessão de acesso. Com
UnsafeMode = false(o padrão), o token é vinculado à sessão ASP.NET da requisição que o abriu: uma entradasecure-{token}é gravada nessa sessão. Portanto, a abertura deve ser executada em uma requisição com estado de sessão — veja Sessões & Segurança. - O token é devolvido. Ele é o único identificador que o navegador precisa para tudo que 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 stream 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 requisição:
| Consulta | Propósito |
|---|---|
?token=…&page=N | Imagem de página renderizada (PNG) |
?token=…&page=N&thumb=1 | Miniatura |
?token=…&zoom=… | Renderização de página ampliada |
?token=…&search=term | Pesquisa em texto completo (restrita por licença) |
?token=…&bookmarks | Estrutura do documento e marcadores |
?token=…© / &showlinks / &fileFormat | Cópia de texto, hyperlinks e informações de formato |
?token=…&meta | Metadados técnicos DICOM — não disponíveis neste pacote (responde 404) |
?token=…&action=rotate/flip/close | Ações de página e fechamento explícito (POST) |
?token=…&AnnSave=… / &AnnLoad | Salvar e carregar anotações |
Cada requisição é verificada primeiro:
- Sem token →
404, ou um banner de versão quandoShowDoconutInfo = 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 mostrá‑las onde a página estaria. Uma verificação de monitoramento que observa apenas o código de status as reportará como páginas servidas; uma página real tem 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 requisição atual e revoga o token. É opcional — a expiração deslizante faz a mesma limpeza — mas para documentos grandes libera memória assim que o usuário termina. Do navegador, objViewer.Close(true) envia a requisiçã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 ocioso além de
DocOptions.TimeOutprecisa ser reaberto. Viewerpode ser resolvido e compartilhado livremente; as sessões carregam todo o estado.
Esta página foi útil?