Cómo funciona el visor

El ciclo de vida de la solicitud de documento

Doconut renderiza documentos como imágenes paginadas servidas a través del middleware ASP.NET Core. Entender el ciclo de vida — apertura, token, solicitudes de página, cierre — explica casi todo el comportamiento que observarás, incluidos los mensajes de error.

Las tres partes móviles

  • Viewer — el servicio público que inyectas. Abre documentos y devuelve tokens de sesión.
  • La sesión del documento — un objeto del lado del servidor que mantiene el documento cargado, indexado por un token en IMemoryCache.
  • The Doconut middleware — añadido por UseDoconut(); responde a cada solicitud que hace el widget del navegador (pages, thumbnails, search, annotations, …), siempre autenticado por el token.

Viewer es sin estado — por diseño

Viewer está sellado, no mantiene estado de documento por solicitud, y deliberadamente no implementa IDisposable. Las sesiones viven independientemente en el gestor de sesiones y se limpian por expiración de caché o por un CloseDocument(token) explícito.

Inyéctalo donde lo necesites:

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

Qué ocurre dentro de OpenDocumentAsync

  1. License gate. Una licencia rechazada o caducada por versión (en lista negra, manipulada, o una compilación fuera de la ventana de actualización de la licencia) lanza un LicenseException inmediatamente, con la razón del rechazo como mensaje — la apertura nunca se degrada silenciosamente para una licencia inválida (en contraste con una ausente). Una licencia Temporal o de suscripción caducada por calendario es la excepción: no lanza — se degrada a una marca de agua.
  2. Session creation. La fábrica del visor elige el visor de formato correcto para la extensión del archivo y carga el documento (ver Rendering Pipeline). La sesión se almacena en IMemoryCache bajo un nuevo token GUID con una expiración deslizante — DocOptions.TimeOut minutos, por defecto 60. Cada solicitud de página restablece el temporizador.
  3. Security registration. Con UnsafeMode = false (el predeterminado), el token está vinculado a la sesión ASP.NET del llamador: se escribe un marcador secure-{token} en la sesión, de modo que solo la sesión del navegador que abrió el documento pueda solicitar sus páginas.
  4. The token is returned. Es la única credencial para todo lo que sigue.

Las tres sobrecargas difieren solo en la entrada: una ruta de archivo, una ruta de archivo más una configuración por formato (PdfConfig, WordConfig, …), o un Stream más un FileInfo cuya extensión determina la detección de formato.

Cómo el widget obtiene páginas

El widget cliente llama al middleware Doconut con el token en la cadena de consulta. Lo que hace el middleware depende de la solicitud:

ConsultaPropósito
?token=…&page=NImagen de página renderizada (PNG)
?token=…&page=N&thumb=1Miniatura
?token=…&zoom=…Renderizado de página ampliada
?token=…&search=termBúsqueda de texto completo (con control de licencia)
?token=…&bookmarksEsquema del documento/marcadores
?token=…&copy / &showlinks / &fileFormat / &metaCopiar texto, hipervínculos, información de formato, metadatos técnicos DICOM
?token=…&action=rotate/flip/closeAcciones de página y cierre explícito
?token=…&AnnSave=… / &AnnLoadGuardar/cargar anotaciones

Cada una de estas rutas se valida primero:

  • No token → el middleware devuelve 404 (o un banner de versión cuando ShowDoconutInfo = true).
  • Unknown or expired token → una imagen de error con Document session not found. Please re-open document.
  • Session middleware missing (con UnsafeMode = false) → HTTP 500 con Session middleware not configured. Call UseSession() before UseDoconut().
  • Token opened by a different browser session → una imagen de error con You Are Not Authorized To View This Page.

Servir páginas desde almacenamiento compartido en lugar del nodo de apertura es una disposición completamente diferente; vea Despliegues Distribuidos.

Cerrando un documento

csharp
viewer.CloseDocument(token);

CloseDocument elimina la sesión de la caché (lo que dispone el motor de documento subyacente y libera su memoria inmediatamente), borra el marcador secure-{token}, y revoca la concesión de acceso. Llamarlo es opcional — la expiración deslizante realiza la misma limpieza automáticamente — pero para documentos grandes es la forma cortés de liberar memoria en el momento en que el usuario termina.

Conclusiones

  • Un documento abierto = una sesión = un token. Los tokens son por sesión de navegador, no URLs globales.
  • El token expira en una ventana deslizante; un visor dejado inactivo más allá de DocOptions.TimeOut necesita volver a abrirse.
  • Viewer puede ser inyectado y compartido libremente; las sesiones llevan todo el estado.

¿Fue útil esta página?