Risoluzione dei problemi
Diagnostica errori comuni
Ogni messaggio qui sotto è il testo letterale prodotto da Doconut, organizzato per sintomo. Trova il tuo errore, applica la correzione.
Il visualizzatore non mostra nulla
Area del visualizzatore vuota, console del browser piena di 404 per /doconut-res/...
UseDoconutResources() è mancante, o posizionato dopo UseDoconut(). Deve essere il primo nella pipeline.
Il visualizzatore segnala The viewer handler could not be reached (no response).
La richiesta non ha mai ricevuto una risposta. Una causa comune è un BasePath che inizia con /: '/doconut' diventa //doconut/DocImage.axd, una richiesta a un altro host. Scrivila senza la barra iniziale (BasePath: 'doconut').
Il visualizzatore segnala Please make sure your middleware is configured.
Il punto finale della pagina ha risposto 404: UseDoconut() non è montato dove punta il BasePath del client. Con app.Map("/doconut", branch => branch.UseDoconut()), il client usa BasePath: 'doconut'.
HTTP 500 con:
Session middleware not configured. Call UseSession() before UseDoconut().La sicurezza dei token di Doconut (attiva per impostazione predefinita) richiede lo stato di sessione ASP.NET. Aggiungi builder.Services.AddSession() e app.UseSession() prima del ramo middleware di Doconut. Lo stato di sessione richiede anche una cache: in un'app minimal-API aggiungi builder.Services.AddDistributedMemoryCache(), oppure l'app si arresta all'avvio con Unable to resolve service for type 'IDistributedCache' (le app MVC e Razor Pages ne registrano già una).
Un'immagine di errore nell'area della pagina che mostra:
You Are Not Authorized To View This Page.Il token è stato aperto da una sessione del browser diversa. Cause tipiche: il cookie di sessione non raggiunge le richieste della pagina (configurazione cross-origin, politica SameSite, un client API senza contenitore di cookie), o l'app è stata riavviata (nuove chiavi di sessione). Questo è lo strato di sicurezza che funziona come progettato — vedi Core Concepts → Sessions & Security. Il rifiuto è un'immagine servita con lo stato 200, quindi un monitor che controlla solo i codici di stato lo conta come una pagina.
Un'immagine di errore che mostra:
Document session not found. Please re-open document.Il token è scaduto (finestra mobile, predefinita 60 minuti — DocOptions.TimeOut) o la sessione è stata chiusa. Riapri il documento per ottenere un nuovo token.
Il server è a posto ma la pagina si comporta in modo errato — senza errori da nessuna parte
Queste sono le modalità di errore da sospettare per prime dopo aver portato avanti un'applicazione. Tutte e tre lasciano il server funzionante perfettamente, rendono correttamente il documento e non segnalano nulla nella console del browser.
Un indicatore di caricamento che non si ferma mai. I callback del tuo visualizzatore sono dichiarati come funzioni globali nominate con l'ID del contenitore — ctlDoc_OnViewerReady() e simili. Il visualizzatore precedente cercava quei nomi; questo non lo fa. Il gestore che avrebbe nascosto l'indicatore semplicemente non viene mai eseguito. Passa le funzioni come opzioni invece:
function ctlDoc_OnViewerBusy() { /* mostra il tuo indicatore di attività */ }
function ctlDoc_OnViewerReady() { /* nascondilo */ }
function ctlDoc_Copy(text) { /* usa il testo copiato */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* segnala l'avanzamento */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... le tue opzioni esistenti ...
onViewerBusy: ctlDoc_OnViewerBusy,
onViewerReady: ctlDoc_OnViewerReady,
onCopy: ctlDoc_Copy,
onAutoLoadStatus: ctlDoc_AutoLoadStatus
});Il documento dietro l'indicatore è a posto. L'elenco completo delle opzioni è in ViewerConfig.
Icone del visualizzatore mancanti o chrome, pagine altrimenti corrette. ResPath è vuoto o punta alla radice dell'applicazione — corretto nella libreria precedente, errato qui. Deve indicare il prefisso che UseDoconutResources() monta:
ResPath: 'doconut-res/images' // oppure '<your ResourcesPath>/images'Riquadri rotti per pagine successive quando si serve da storage condiviso. Le pagine ancora in scrittura rispondono 202 Accepted. Un client senza retryOn409: true interpreta ciò come un'immagine fallita. Vedi Distributed Deployments.
Apertura di un documento fallita
LicenseException con un messaggio di rifiuto — il file di licenza è stato trovato ma rifiutato (firma non valida, manomesso, nella lista nera, o una build al di fuori della finestra di versione/aggiornamento della licenza). Questo stato blocca l'apertura (fail-fast) anziché degradare a un watermark; leggi License.RejectionMessage per il motivo.
LicenseException:
This document type requires the 'Dicom' plugin license.L'estensione è gestita solo da un plugin (qui: DICOM). Il plugin è registrato, ma nessuna licenza ne garantisce più la capacità — tipicamente una licenza Temporanea scaduta dopo l'avvio dell'app. Installa una licenza che la conceda e verifica IsCapabilityGranted(LicenseCapability.Dicom) su IDoconutLicenseService. Un diritto non temporaneo mancante o insufficiente normalmente fallisce prima, durante AddDoconut().
FormatNotSupportedException:
Document format '<extension>' is not supported.Nessun visualizzatore — integrato, plugin o personalizzato — dichiara di supportare quell'estensione. Controlla l'elenco dei formati supportati; per i tuoi formati, DoconutOptions.RegisterViewer può aggiungerne uno.
InvalidDataException — il contenuto del file è corrotto o non corrisponde alla sua estensione (ad es. un file rinominato). Convalida i caricamenti prima di aprire.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().Hai risolto DocumentConverter senza registrare il plugin Converter.
Avvio fallito
InvalidOperationException che menziona un plugin registrato tramite AddPlugin — la licenza non temporanea corrente non concede quella capacità al plugin. Rimuovi la registrazione o installa una licenza che la conceda. Una licenza mancante e un file legacy TRIAL non concedono capacità al plugin.
ArgumentException da AddDoconut():
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.Validazione delle opzioni fail-fast — correggi il percorso incriminato.
Errori di compilazione / dipendenze
Il pacchetto non si installerà affatto — Doconut.NETStandard mira a
netstandard2.1, quindi NuGet rifiuta un progetto .NET Framework. Questo non è un errore di ripristino risolvibile: .NET Framework non può consumare netstandard2.1. Usa il pacchetto Doconut.NETFramework invece.
Errore del compilatore CS1705, o a runtime durante l'apertura di un documento:
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'Il tuo progetto ha fissato System.Text.Json o System.Text.Encodings.Web al di sotto della versione 9.0.x
delle dipendenze dichiarate da Doconut.NETStandard. Rimuovi il downgrade e lascia che NuGet ripristini il
grafo dei pacchetti (System.Text.Json 9.0.0 e System.Text.Encodings.Web 9.0.0 come dichiarato
dal pacchetto).
Un muro di errori di compilazione subito dopo l'aggiornamento del pacchetto — è previsto.
26.8.0 ha una superficie API diversa da 26.7.0, non è un aggiornamento compatibile. La maggior parte degli
errori sono le righe using che sono state spostate nello spazio dei nomi radice Doconut; affrontale
Migra a .NET Standard 2.1 invece di correggerle una per una.
TypeInitializationException sul primo file di presentazione:
Could not load ... System.Drawing.Common, Version=6.0.0.0Il motore di presentazione richiede rigidamente System.Drawing.Common 6.0.0 (dichiarato dal pacchetto). Non rimuovere o sovrascrivere quella dipendenza — ogni apertura di PPT/PPTX/PPS/POT/ODP fallisce senza di essa.
L'output sembra errato
Le pagine mostrano un watermark — l'app è in stato di valutazione: nessun file di licenza trovato, una licenza Temporanea scaduta, o un dominio non valido. Con una licenza Temporanea attiva, solo l'output del plugin è marcato. Una build rilasciata dopo la data di sottoscrizione di una licenza a pagamento non è watermarked: l'apertura genera LicenseException. Esamina IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — il riferimento IDoconutLicenseService della pagina Licensing mostra un endpoint pronto all'uso.
I documenti legacy mostrano testo illeggibile — le codifiche delle pagine di codice non vengono caricate per impostazione predefinita. Aggiungile una volta all'avvio:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Font errati o sostituiti — il server non dispone dei font del documento. Installali, o indirizza FontFolders (su WordConfig/PptConfig) a una cartella che li contiene.
Un'annotazione immagine appare nel visualizzatore ma l'esportazione mostra una casella "Image blocked" — l'host dell'immagine ha un indirizzo privato o di loopback, che il server rifiuta di recuperare. Vedi Annotazioni.
Funzionalità attiva in valutazione, silenziosa in produzione
La classica sorpresa del go‑live: una licenza Temporanea attiva garantisce ogni capacità; la tua licenza acquistata garantisce solo ciò che hai comprato. I pacchetti di ricerca e annotazione possono scomparire quando le loro capacità sono assenti. I plugin Converter registrati o DICOM con una licenza non temporanea insufficiente falliscono durante AddDoconut(). Confronta IsCapabilityGranted(...) con ogni funzionalità che abiliti prima della distribuzione.
La ricerca non trova nulla (o troppo poco)
- Per un PDF diretto,
AllowSearchnon era abilitato al momento dell’apertura. Word, Excel e PowerPoint espongono lo stesso interruttore attraverso i loroPdfConfignidificati. - Il contenuto è scansionato/solo immagine, quindi la Ricerca normale non ha alcuno strato di testo da confrontare. Usa una fonte contenente testo o una proiezione PDF che preservi il testo.
- HTML e MS Project (MPP) non sono ricercabili con le impostazioni predefinite — imposta
DefaultRender = falsein modo che vengano renderizzati tramite una proiezione PDF con uno strato di testo nativo. Word, Excel, PowerPoint, TXT, Visio, email, EPUB e MHT ricercano con le impostazioni predefinite del loro catalogo. objViewer.CanSearch()èfalsedopo l’inizializzazione — il formato risolto non ha un percorso di ricerca standard. Questo risultato è separato dalla licenza di Ricerca; verifica entrambi.- La pagina legge il valore di ritorno di
objViewer.Search(...)— il conteggio arriva nel suo terzo argomento, una callback.
Ancora bloccato?
Isola il problema rispetto all’app Quick Start minimale; se si riproduce lì, contatta il supporto con il documento, il tuo Program.cs e l’output della diagnostica della licenza.
Questa pagina è stata utile?