Risoluzione dei problemi

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.

HTTP 500 con:

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

Il token di sicurezza di Doconut (attivo per impostazione predefinita) richiede lo stato di sessione ASP.NET. Aggiungi builder.Services.AddSession() e app.UseSession() prima del ramo middleware Doconut. Lo stato di sessione richiede anche una cache: in un'app minimal‑API aggiungi builder.Services.AddDistributedMemoryCache(), altrimenti l'app si arresta all'avvio con Unable to resolve service for type 'IDistributedCache' (le app MVC e Razor Pages registrano già una).

Un'immagine di errore nell'area della pagina che riporta:

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 Concetti di base → Sessioni e Sicurezza.

Un'immagine di errore che riporta:

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 anomalo — 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.

Uno spinner occupato che non si ferma mai. Le tue callback del visualizzatore sono dichiarate come funzioni globali nominate in base all'ID del contenitore — ctlDoc_OnViewerReady() e simili. Il visualizzatore precedente cercava quei nomi; questo non lo fa. Il gestore che avrebbe nascosto lo spinner semplicemente non viene mai eseguito. Passa le funzioni come opzioni invece:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Il documento dietro lo spinner è corretto. La lista completa delle opzioni è in ConfigurazioneViewer.

Icone del visualizzatore o chrome mancanti, 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'   // or '<your ResourcesPath>/images'

Riquadri rotti per pagine successive quando si serve da storage condiviso. Le pagine che sono ancora in scrittura rispondono 202 Accepted. Un client senza retryOn409: true le tratta come un'immagine fallita. Vedi Distribuzioni distribuite.

L'apertura di un documento fallisce

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) e la capacità non è più concessa. Registra il plugin e verifica lic.IsCapabilityGranted(LicenseCapability.Dicom). Un'entitlement mancante o insufficiente non temporanea normalmente fallisce prima durante AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

Nessun visualizzatore — integrato, plugin o personalizzato — riconosce quell'estensione. Controlla la lista 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 esempio un file rinominato). Convalida gli upload 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 corrente non temporanea non concede quella capacità del plugin. Rimuovi la registrazione o installa una licenza che la conceda. Una licenza mancante e un file legacy TRIAL non concedono alcuna capacità del 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 errato.

Errori di compilazione / dipendenze

Il pacchetto non si installerà affatto — Doconut.NETStandard 26.8.0 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 quando si apre 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 a una versione inferiore alla 9.0.x dichiarata 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 nel pacchetto 26.8.0 verificato).

Una valanga di errori di compilazione subito dopo l'aggiornamento del pacchetto — è previsto. La 26.8.0 ha una superficie API diversa dalla 26.7.0, non è un aggiornamento compatibile. La maggior parte degli errori sono le linee using spostate nel namespace radice Doconut; affrontali seguendo Migra a .NET Standard 2.1 anziché correggerli uno per uno.

TypeInitializationException sul primo file di presentazione:

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

Il motore di presentazione richiede obbligatoriamente System.Drawing.Common 6.0.0 (dichiarato dal pacchetto). Non rimuovere né sovrascrivere quella dipendenza — ogni apertura di PPT/PPTX/PPS/POT/ODP fallisce senza di essa.

L'output sembra errato

Le pagine mostrano una filigrana — l'app è in stato di valutazione: nessun file di licenza trovato, una finestra temporanea o di abbonamento scaduta, o un dominio non valido. Ispeziona IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — il riferimento della pagina Licensing a IDoconutLicenseService mostra un endpoint pronto all'uso.

I documenti legacy visualizzano testo illeggibile — le codifiche di pagina codice non vengono caricate per impostazione predefinita. Aggiungile una sola volta all'avvio:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Font errati o sostituiti su Linux/Docker — il contenitore non contiene i font del documento. Imposta FontFolders (su WordConfig/PptConfig) verso una directory di font montata.

Le presentazioni si aprono ma non vengono renderizzate su Linux/macOS — il renderer PPT/PPTX/PPS/POT/ODP corrente richiede libgdiplus nativo più System.Drawing.EnableUnixSupport=true. Il pacchetto fornisce System.Drawing.Common 6.0.0 perché è l'ultima versione che rispetta questa opzione.

La funzionalità funzionava in valutazione, silenziosa in produzione

La classica sorpresa al go‑live: una licenza Temporanea attiva concede tutte le capacità; la tua licenza acquistata concede solo ciò che hai comprato. I bundle di ricerca e annotazione possono scomparire quando le loro capacità sono assenti. Plugin Converter o DICOM registrati con una licenza non temporanea insufficiente falliscono durante AddDoconut(). Confronta IsCapabilityGranted(...) con ogni funzionalità che abiliti prima del dispiegamento.

La ricerca non trova nulla (o troppo poco)

• Per un PDF diretto, AllowSearch non era abilitato al momento dell'apertura. Word, Excel e PowerPoint espongono lo stesso interruttore tramite il loro PdfConfig nidificato.
• Il contenuto è scansionato / solo immagine, quindi la Ricerca normale non ha alcuno strato di testo da abbinare. Usa una sorgente con testo o una proiezione PDF che preservi il testo.
• HTML e MS Project (MPP) non sono ricercabili con le impostazioni predefinite — imposta DefaultRender = false affinché vengano renderizzati tramite una proiezione PDF con strato di testo nativo. Word, Excel, PowerPoint, TXT, Visio, email, EPUB e MHT sono ricercabili con le impostazioni predefinite del loro catalogo.
• objViewer.CanSearch() è false dopo l'inizializzazione — il formato risolto non ha un percorso di ricerca standard. Questo risultato è separato dalla licenza di Ricerca; verifica entrambi.

Ancora bloccato?

Isola il problema nell'app minimal Quick Start; se si riproduce lì, contatta il supporto con il documento, il tuo Program.cs e l'output della diagnostica della licenza.