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. Scrivilo 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 utilizza BasePath: 'doconut'.

HTTP 500 con:

text
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 necessita anche di 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:

text
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. 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:

text
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) invece di degradare a un watermark; leggi License.RejectionMessage per il motivo.

LicenseException:

text
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:

text
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:

text
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 tale capacità del plugin. Rimuovi la registrazione o installa una licenza che la conceda. Una licenza mancante e un file legacy TRIAL non concedono capacità del plugin.

ArgumentException da AddDoconut():

text
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 build / dipendenze

Errore del compilatore CS1705, o a runtime durante l'apertura di un documento:

text
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 al di sotto delle dipendenze 8.0.x dichiarate da Doconut.NET8. Rimuovi il downgrade e lascia che NuGet ripristini il grafo dei pacchetti (System.Text.Json 8.0.5 e System.Text.Encodings.Web 8.0.0).

L'output sembra errato

Le pagine hanno una filigrana — 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 è contrassegnato da filigrana. Una build rilasciata dopo la data di sottoscrizione di una licenza a pagamento non ha filigrana: l'apertura genera LicenseException. Controlla 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 di pagina codice non vengono caricate per impostazione predefinita su .NET 8. Aggiungile una volta all'avvio:

csharp
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. Su Linux, vedi sotto.

Un'annotazione immagine è visibile 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.

Linux

L'apertura di qualsiasi documento fallisce con:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Installa la libreria di configurazione dei font: apt-get install -y libfontconfig1 (fontconfig su RHEL/Fedora). Vedi Installazione.

L'apertura di qualsiasi documento fallisce con:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

L'applicazione fa riferimento a una versione più recente di SkiaSharp, direttamente o tramite un'altra libreria. Aggiungi SkiaSharp.NativeAssets.Linux alla stessa versione di quel SkiaSharp.

L'apertura di qualsiasi documento fallisce con:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

L'host non è una piattaforma supportata. Alpine e altre distribuzioni basate su musl non sono supportate: usa un'immagine basata su Debian o Ubuntu.

Il testo è più largo o più stretto rispetto a Windows, o le interruzioni di riga sono diverse — i font del documento non sono installati, quindi Doconut usa il font installato più vicino. Installa font metricamente compatibili (fonts-liberation per Arial, Times New Roman e Courier New; fonts-crosextra-carlito e fonts-crosextra-caladea per Calibri e Cambria), oppure copia i tuoi font con licenza in /usr/share/fonts/ ed esegui fc-cache -f. Il testo asiatico mostrato come caselle vuote necessita di fonts-noto-cjk.

Funzionalità funzionante in valutazione, silenziosa in produzione

La classica sorpresa al go‑live: una licenza Temporanea attiva garantisce tutte le funzionalità; la tua licenza acquistata garantisce solo ciò che hai comprato. I pacchetti di ricerca e annotazione possono scomparire quando le loro funzionalità 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 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 i loro PdfConfig nidificati.
  • 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 nelle impostazioni predefinite — imposta DefaultRender = false in modo che vengano renderizzati tramite una proiezione PDF con uno strato di testo nativo. Word, Excel, PowerPoint, TXT, Visio, email, EPUB e MHT ricercano nelle loro impostazioni predefinite del 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.
  • 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?