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().

La sicurezza del 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 è il livello di sicurezza che funziona come previsto — vedi Concetti di base → Sessioni & Sicurezza.

Un'immagine di errore che mostra:

Document session not found. Please re-open document.

Il token è scaduto (finestra scorrevole, predefinita 60 minuti — DocOptions.TimeOut) o la sessione è stata chiusa. Riapri il documento per ottenere un nuovo token.

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 blacklist, o una build al di fuori della finestra di versione/aggiornamento della licenza). Questo stato blocca l'apertura (fail‑fast) anziché degradare a filigrana; 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 diritto non temporaneo mancante o insufficiente normalmente fallisce prima durante AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

Nessun visualizzatore — integrato, plugin o personalizzato — riconosce quell'estensione. Controlla l'elenco dei formati supportati; per i tuoi formati personalizzati, DoconutOptions.RegisterViewer può aggiungerne uno.

InvalidDataException — il contenuto del file è corrotto o non corrisponde alla sua estensione (ad es. un file rinominato). Convalida gli upload prima di aprirli.

InvalidOperationException:

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

Hai risolto DocumentConverter senza registrare il plugin Converter.

Avvio fallisce

InvalidOperationException che menziona un plugin registrato tramite AddPlugin — la licenza non temporanea corrente 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 capacità di 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

Errore del compilatore CS1705, o a runtime quando si apre un documento:

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

Il tuo progetto ha fissato System.Text.Json o System.Text.Encodings.Web a una versione inferiore alla 8.0.x dichiarata da Doconut.NET6. Rimuovi il downgrade e lascia che NuGet ripristini il grafo dei pacchetti (System.Text.Json 8.0.6 e System.Text.Encodings.Web 8.0.0 nel pacchetto auditato 26.7.0).

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 appare 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 vengono visualizzati con testo illeggibile — le codifiche delle code page non vengono caricate per impostazione predefinita su .NET 6. Aggiungile una sola volta all'avvio:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Font errati o sostituiti su Linux/Docker — il container non dispone dei 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, ma è 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. I plugin Converter o DICOM registrati con una licenza non temporanea insufficiente falliscono durante AddDoconut(). Confronta IsCapabilityGranted(...) con ogni funzionalità che abiliti prima del deployment.

La ricerca non trova nulla (o trova 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 annidato.
• Il contenuto è scansionato/solo immagine, quindi la Ricerca normale non ha alcuno strato di testo da confrontare. 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 così vengono renderizzati tramite una proiezione PDF con uno strato di testo nativo. Word, Excel, PowerPoint, TXT, Visio, email, EPUB e MHT ricercano con le loro impostazioni di catalogo predefinite.
• objViewer.CanSearch() è false dopo l'inizializzazione — il formato risolto non ha un percorso di ricerca standard. Questo verdetto è separato dalla licenza di Ricerca; verifica entrambi.

Ancora bloccato?

Isola il problema confrontandolo con l'app Quick Start minimale; se si riproduce lì, contatta il supporto fornendo il documento, il tuo Program.cs e l'output diagnostico della licenza.