Solución de problemas

Diagnosticar errores comunes

Cada mensaje a continuación es el texto literal que produce Doconut, organizado por síntoma. Encuentra tu error, aplica la solución.

El visor no muestra nada

Área del visor vacía, consola del navegador llena de 404s para /doconut-res/...
UseDoconutResources() falta, o está colocado después de UseDoconut(). Debe aparecer primero en la canalización.

El visor informa The viewer handler could not be reached (no response).
El pedido nunca recibió una respuesta. Una causa común es un BasePath que comienza con /: '/doconut' se convierte en //doconut/DocImage.axd, una solicitud a otro host. Escríbelo sin la barra inicial (BasePath: 'doconut').

El visor informa Please make sure your middleware is configured.
El punto final de la página respondió 404: UseDoconut() no está montado donde apunta el BasePath del cliente. Con app.Map("/doconut", branch => branch.UseDoconut()), el cliente usa BasePath: 'doconut'.

HTTP 500 con:

text
Session middleware not configured. Call UseSession() before UseDoconut().

La seguridad de tokens de Doconut (activada por defecto) necesita el estado de sesión de ASP.NET. Añade builder.Services.AddSession() y app.UseSession() antes de la rama de middleware de Doconut. El estado de sesión también necesita una caché: en una aplicación minimal-API añade builder.Services.AddDistributedMemoryCache(), o la aplicación se detiene al iniciar con Unable to resolve service for type 'IDistributedCache' (las aplicaciones MVC y Razor Pages ya registran una).

Una imagen de error en el área de la página que dice:

text
You Are Not Authorized To View This Page.

El token fue abierto por una sesión de navegador diferente. Causas típicas: la cookie de sesión no llega a las solicitudes de la página (configuración cross-origin, política SameSite, un cliente API sin almacén de cookies), o la aplicación se reinició (nuevas claves de sesión). Esta es la capa de seguridad funcionando como se diseñó — ver Conceptos básicos → Sesiones y Seguridad. La denegación es una imagen servida con el estado 200, por lo que un monitor que solo verifica códigos de estado la cuenta como una página.

Una imagen de error que dice:

text
Document session not found. Please re-open document.

El token expiró (ventana deslizante, 60 minutos por defecto — DocOptions.TimeOut) o la sesión se cerró. Vuelve a abrir el documento para obtener un token nuevo.

El servidor está bien pero la página se comporta mal — sin error en ninguna parte

Estos son los modos de falla que se deben sospechar primero al trasladar una aplicación. Los tres dejan el servidor funcionando perfectamente, renderizan el documento correctamente y no informan nada en la consola del navegador.

Un spinner activo que nunca se detiene. Tus callbacks del visor están declarados como funciones globales nombradas según el id del contenedor — ctlDoc_OnViewerReady() y sus amigos. El visor anterior buscaba esos nombres; este no lo hace. El manejador que habría ocultado el spinner simplemente nunca se ejecuta. Pasa las funciones como opciones en su lugar:

javascript
function ctlDoc_OnViewerBusy() { /* muestra tu indicador de actividad */ }
function ctlDoc_OnViewerReady() { /* ocúltalo */ }
function ctlDoc_Copy(text) { /* usa el texto copiado */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* informar del progreso */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... tus opciones existentes ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

El documento detrás del spinner está bien. La lista completa de opciones está en ViewerConfig.

Faltan íconos del visor o el marco, las páginas están correctas de otro modo. ResPath está vacío o apunta a la raíz de la aplicación — correcto en la biblioteca anterior, incorrecto aquí. Debe nombrar el prefijo que UseDoconutResources() monta:

javascript
ResPath: 'doconut-res/images'   // o '<your ResourcesPath>/images'

Mosaicos rotos para páginas posteriores al servir desde almacenamiento compartido. Las páginas que aún se están escribiendo responden 202 Accepted. Un cliente sin retryOn409: true trata eso como una imagen fallida. Ver Distributed Deployments.

Fallar al abrir un documento

LicenseException con un mensaje de rechazo — se encontró el archivo de licencia pero fue rechazado (firma inválida, manipulado, en lista negra, o una compilación fuera de la ventana de versión/actualización de la licencia). Este estado bloquea la apertura (fail-fast) en lugar de degradar a una marca de agua; lea License.RejectionMessage para conocer la razón.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

La extensión es manejada solo por un complemento (aquí: DICOM). El complemento está registrado, pero ya ninguna licencia otorga su capacidad — típicamente una licencia Temporal que expiró después de que la aplicación se inició. Instale una licencia que la conceda y verifique IsCapabilityGranted(LicenseCapability.Dicom) en IDoconutLicenseService. Una autorización no temporal faltante o insuficiente normalmente falla antes, durante AddDoconut().

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

Ningún visor — incorporado, complemento o personalizado — reconoce esa extensión. Verifique la lista de formatos admitidos; para sus propios formatos, DoconutOptions.RegisterViewer puede agregar uno.

InvalidDataException — el contenido del archivo está corrupto o no coincide con su extensión (p. ej., un archivo renombrado). Valide las cargas antes de abrir.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Usted resolvió DocumentConverter sin registrar el complemento Converter.

Fallas al iniciar

InvalidOperationException que menciona un complemento registrado a través de AddPlugin — la licencia no temporal actual no otorga esa capacidad al complemento. Elimine el registro o instale una licencia que la conceda. Una licencia faltante y un archivo legado TRIAL no otorgan capacidades de complemento.

ArgumentException de AddDoconut():

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.

Validación de opciones fail-fast — corrija la ruta problemática.

Errores de compilación / dependencias

El paquete no se instalará en absoluto — Doconut.NETStandard apunta a netstandard2.1, por lo que NuGet rechaza un proyecto .NET Framework. Este no es un error de restauración resoluble: .NET Framework no puede consumir netstandard2.1. Use el paquete Doconut.NETFramework en su lugar.

Error del compilador CS1705, o en tiempo de ejecución al abrir un documento:

text
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

Su proyecto fijó System.Text.Json o System.Text.Encodings.Web por debajo de las dependencias 9.0.x declaradas por Doconut.NETStandard. Elimine la degradación y permita que NuGet restaure el grafo de paquetes (System.Text.Json 9.0.0 y System.Text.Encodings.Web 9.0.0 según lo declarado por el paquete).

Una gran cantidad de errores de compilación inmediatamente después de actualizar el paquete — esto es esperado. 26.8.0 tiene una superficie de API diferente a 26.7.0, no es una actualización compatible. La mayoría de los errores son las líneas using que se movieron al espacio de nombres raíz Doconut; siga la guía Migrar a .NET Standard 2.1 en lugar de parchearlos uno a uno.

TypeInitializationException en el primer archivo de presentación:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

El motor de presentaciones requiere estrictamente System.Drawing.Common 6.0.0 (declarado por el paquete). No elimine ni sobrescriba esa dependencia — la apertura de cualquier PPT/PPTX/PPS/POT/ODP falla sin ella.

La salida se ve incorrecta

Las páginas llevan una marca de agua — la aplicación está en estado de evaluación: no se encontró archivo de licencia, una licencia Temporal caducada, o un dominio inválido. Con una licencia Temporal activa, solo la salida del complemento lleva marca de agua. Una compilación publicada después de la fecha de suscripción de una licencia paga no lleva marca de agua: la apertura lanza LicenseException. Examine IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la referencia IDoconutLicenseService de la página de Licencias muestra un punto final listo.

Los documentos heredados muestran texto distorsionado — las codificaciones de página de código no se cargan por defecto. Añádalas una vez al iniciar:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Fuentes incorrectas o sustituidas — el servidor no tiene las fuentes del documento. Instálelas, o apunte FontFolders (en WordConfig/PptConfig) a una carpeta que las contenga.

Una anotación de imagen se muestra en el visor pero la exportación tiene un recuadro "Imagen bloqueada" — el host de la imagen tiene una dirección privada o de bucle invertido, que el servidor se niega a obtener. Vea Anotaciones.

La característica funcionó en evaluación, silenciosa en producción

La clásica sorpresa al pasar a producción: una licencia Temporal activa otorga todas las capacidades; tu licencia comprada solo otorga lo que adquiriste. Los paquetes de búsqueda y anotación pueden desaparecer cuando sus capacidades están ausentes. Los complementos Registered Converter o DICOM con una licencia no temporal insuficiente fallan durante AddDoconut(). Compara IsCapabilityGranted(...) con cada característica que habilites antes del despliegue.

La búsqueda no encuentra nada (o muy poco)

  • Para un PDF directo, AllowSearch no estaba habilitado al abrirlo. Word, Excel y PowerPoint exponen el mismo interruptor a través de su PdfConfig anidado.
  • El contenido está escaneado/sólo imagen, por lo que la Búsqueda normal no tiene capa de texto para coincidir. Usa una
    fuente con texto o una proyección PDF que preserve el texto.
  • HTML y MS Project (MPP) no son buscables en sus valores predeterminados — configura DefaultRender = false para que se rendericen mediante una proyección PDF con una capa de texto nativa. Word, Excel, PowerPoint, TXT, Visio, correo electrónico, EPUB y MHT buscan en sus valores predeterminados del catálogo.
  • objViewer.CanSearch() es false después de la inicialización — el formato resuelto no tiene una ruta de búsqueda estándar. Este veredicto es independiente de la licencia de Búsqueda; verifica ambos.
  • La página lee el valor de retorno de objViewer.Search(...) — el recuento llega en su tercer argumento, una función de devolución de llamada.

¿Aún atascado?

Aísla el problema con la aplicación mínima Quick Start; si se reproduce allí, contacta al soporte con el documento, tu Program.cs y la salida de diagnóstico de la licencia.

¿Fue útil esta página?