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 dei 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.

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), oppure l'app è stata riavviata (nuove chiavi di sessione). Questo è lo strato di sicurezza che funziona come previsto — vedi Concetti di base → Sessioni e Sicurezza.

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.

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 una 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 — supporta 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 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 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 TRIAL legacy 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 di compilazione CS1705, o a runtime durante l'apertura di 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 versioni inferiori alle dipendenze 8.0.x dichiarate da Doconut.NET6. Rimuovi il downgrade e consenti a NuGet di ripristinare 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 rigidamente 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 IDoconutLicenseService della pagina Licensing mostra un endpoint pronto all'uso.

I documenti legacy visualizzano testo illeggibile — le codifiche delle pagine di codice non sono caricate per impostazione predefinita su .NET 6. Aggiungile una volta all'avvio:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Font errati o sostituiti su Linux/Docker — il contenitore non ha i font del documento. Imposta FontFolders (su WordConfig/PptConfig) su 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 impostazione.

La 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 pacchetti 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 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 annidato.
• Il contenuto è scansionato/solo immagine, quindi la Ricerca normale non ha uno strato di testo da confrontare. Usa una fonte 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 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 confrontandolo con l'app Quick Start minima; se si riproduce lì, contatta il supporto con il documento, il tuo Program.cs e l'output diagnostico della licenza.