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 basata su token di Doconut (attiva per impostazione predefinita) richiede lo stato di sessione di 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(), altrimenti 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 recita:

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 cookie jar), oppure l'app è stata riavviata (nuove chiavi di sessione). Questo è il livello di sicurezza che funziona come previsto — vedi Core Concepts → Sessions & Security.

Un'immagine di errore che recita:

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 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 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 non temporanea 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.

L'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=10.0.0.0'

Il tuo progetto ha vincolato System.Text.Json / System.Text.Encodings.Web a una versione inferiore a 10.0.x. Rimuovi il downgrade e lascia che NuGet ripristini le versioni dichiarate da Doconut.NET8.

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 un watermark — 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 confuso — le codifiche di pagina codice non vengono caricate per impostazione predefinita su .NET 8. Aggiungi una volta all'avvio:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Font errati o sostituiti su Linux/Docker — il container 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 onora questa opzione.

Una funzionalità funzionava in valutazione, è silenziosa in produzione

La classica sorpresa al go‑live: una licenza Temporanea attiva concede ogni 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 deployment.

La ricerca non trova nulla (o trova 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 alcun livello 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 un livello di testo nativo. Word, Excel, PowerPoint, TXT, Visio, email, EPUB e MHT cercano con le impostazioni predefinite del loro catalogo.
• objViewer.CanSearch() è false dopo l'inizializzazione — il formato risolto non ha un percorso di ricerca standard. Questo verdetto è separato dalla licenza di Search; verifica entrambi.

Ancora bloccato?

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