Risoluzione dei problemi – Documentazione Doconut

Molti errori di System.Web non generano eccezioni visibili: la pagina restituisce un 500 vuoto, un'icona restituisce 404, o una richiesta non ritorna mai. Questa pagina è organizzata in base a ciò che osservi. I messaggi tra virgolette sono il testo letterale prodotto da Doconut.

Sintomi a colpo d'occhio

Cosa vedi	Causa più probabile	Correzione
Ogni richiesta restituisce un `500` vuoto	Un'eccezione in `Application_Start`: un plugin senza licenza, un'opzione non valida, una configurazione di farm incompleta — o un reindirizzamento di binding che indica una versione non presente in `bin\`	Registro eventi di Windows, Applicazione, origine ASP.NET. Vedi Errori di avvio
Alcune pagine MVC restituiscono un `500` vuoto	Razor compila le viste a runtime: la facciata `netstandard` è mancante da `<compilation>`, o la vista utilizza C# più recente di 5 (`?.`, `$"..."`, `nameof`)	Aggiungi la facciata (Installazione); sposta la logica dalla vista al controller
Le pagine mostrano `â€”`, `â€¦` o simili al posto di trattini e accenti	I file di pagina senza byte-order mark vengono letti con la pagina di codice ANSI del server	`<globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />`
La console del browser mostra `404` per `HEAD /DocImage.axd?...&page=1`	Il gestore è registrato senza il verbo `HEAD`	`verb="GET,HEAD,POST"` sul gestore
Il documento viene renderizzato, ma le icone della barra degli strumenti e l'animazione di caricamento sono mancanti	`ResPath` punta alla radice delle risorse, o inizia con `/`	`ResPath: 'doconut-res/images'`
Le richieste `/doconut-res/...` restituiscono `404`	Il modulo risorsa non è registrato, `runAllManagedModulesForAllRequests` è disattivato, o il routing MVC intercetta il percorso	La voce `<modules>`, e `routes.IgnoreRoute("doconut-res/{*pathInfo}")`
Il visualizzatore segnala `The viewer handler could not be reached (no response).`	`BasePath` inizia con `/` (`'/myapp'` diventa `//myapp/…`, un altro host)	`BasePath: '/'` nella radice del sito; `'myapp'` in una directory virtuale
Il visualizzatore segnala `Please make sure your middleware is configured.`	`DocImage.axd` ha risposto `404`: il gestore non è in `Web.config`, il routing MVC lo ha intercettato, o `BasePath` punta altrove	La voce `<handlers>`, `routes.IgnoreRoute("{resource}.axd/{*pathInfo}")`, e `BasePath`
Ogni pagina mostra `You Are Not Authorized To View This Page.`	Il documento è stato aperto in una richiesta senza stato di sessione, lo stato di sessione è disattivato, o il cookie di sessione non raggiunge `DocImage.axd`	Vedi Non autorizzato
Una conversione Web Forms non ritorna mai	La pagina si blocca su `ConvertAsync` — un deadlock	`Async="true"` + `RegisterAsyncTask` (Plugin Convertitore)
Ogni pagina contiene una filigrana di valutazione	Nessuna licenza trovata — non è in `<site root>\wwwroot`	Configurazione Licenza
Un widget si carica, ma la sua prima azione restituisce `404`	Il widget non è abilitato, o il suo `basePath` non è `'/DocImage.axd'`	`options.Add…Widget()`, e `basePath: '/DocImage.axd'`
Il primo documento dopo l'avvio o il riciclo del sito impiega un minuto o più; i successivi sono veloci	I motori dei documenti si caricano al primo apertura, e l'antivirus in tempo reale li scansiona durante il caricamento	Riscalda il sito e mantieni il pool attivo — vedi Il primo documento dopo un avvio
Un caricamento di grandi dimensioni mostra una pagina di errore IIS	Il caricamento supera `maxRequestLength` (KB) o `maxAllowedContentLength` (byte)	Aumenta entrambi al di sopra del tuo file più grande o del limite del widget

Errori di avvio

Un'eccezione lanciata in Application_Start non raggiunge il browser: ogni richiesta restituisce un 500 vuoto, e il registro IIS non mostra nulla di utile. L'eccezione si trova nel registro eventi di Windows (Visualizzatore eventi → Registri di Windows → Applicazione, origine ASP.NET). I più comuni:

Un plugin senza licenza:

text

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

Il Doconut.Viewer.<Capability>.lic del plugin deve trovarsi in wwwroot, accanto a Doconut.Viewer.lic. Una licenza mancante e un file legacy TRIAL non concedono alcuna funzionalità al plugin.

Opzioni non valide:

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.

Un assembly che non può essere caricato.

ASP.NET carica ogni assembly in bin\ quando l'applicazione avvia, quindi un reindirizzamento di binding in Web.config che indica una versione assente da bin\ blocca l'intero sito. Copia i reindirizzamenti generati da NuGet (per un progetto in stile SDK, da bin\<YourApp>.dll.config) invece di modificarli manualmente, e copiali nuovamente dopo gli aggiornamenti dei pacchetti.

Non sei autorizzato a visualizzare questa pagina.

La pagina è rifiutata perché la sessione ASP.NET richiedente non ha mai ricevuto il documento. Verifica, in ordine:

L'apertura è stata eseguita con lo stato di sessione. I controller MVC e le pagine Web Forms lo hanno. Un IHttpHandler personalizzato che apre documenti deve implementare System.Web.SessionState.IRequiresSessionState, altrimenti non ha sessione da concedere.
Lo stato di sessione è attivo. <sessionState mode="Off" /> rifiuta ogni pagina.
Il cookie raggiunge il gestore. Le richieste same-origin del widget trasportano ASP.NET_SessionId; uno script, una chiamata server-to-server, o una pagina cross-origin senza cookie non lo fanno.
Web farm: l'apertura ha legato il browser (DocOptions.BrowserId) e la pagina passa il ticket (objViewer.View(token, access)); ogni nodo utilizza la stessa chiave di firma.

Il rifiuto è un'immagine servita con lo stato 200, circa 2 KB. Un monitor che controlla solo i codici di stato lo conta come una pagina.

Sessione del documento non trovata. Per favore riapri il documento.

Il token è scaduto (finestra mobile, DocOptions.TimeOut, predefinito 60 minuti), il documento è stato chiuso, oppure — su un singolo server — il pool dell'applicazione è stato riciclato. Un riciclo avviene secondo programma, ad ogni modifica Web.config, e dopo il timeout di inattività del pool (20 minuti per impostazione predefinita in IIS). Riapri il documento per ottenere un nuovo token.

L'apertura di un documento fallisce

LicenseException con motivo di rifiuto — il file di licenza è stato trovato ma rifiutato (firma non valida, manomissione, inserimento in blacklist, o una build al di fuori della finestra di versione della licenza). L'apertura è bloccata anziché contrassegnata da filigrana.

LicenseException:

text

This document type requires the 'Dicom' plugin license.

L'estensione è gestita solo da un plugin (qui DICOM) la cui capacità non è concessa.

FormatNotSupportedException — nessun visualizzatore (integrato, plugin o personalizzato) riconosce l'estensione. DoconutOptions.RegisterViewer può aggiungerne uno per i tuoi formati.

InvalidDataException — il contenuto è corrotto o non corrisponde alla sua estensione (un file rinominato). Convalida i caricamenti prima di aprire.

InvalidOperationException:

text

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

DocumentConverter è stato risolto senza registrare il plugin Converter.

L'output sembra errato

Le pagine hanno una filigrana — nessuna licenza è stata trovata, o è scaduta o non copre questa versione. Su IIS, la licenza deve trovarsi in wwwroot sotto la radice del sito (AppContext.BaseDirectory\wwwroot), non in bin\. Controlla IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, License.RejectionMessage).

I documenti legacy mostrano testo illeggibile — registra le codifiche delle pagine di codice una sola volta, all'avvio:

csharp

// Global.asax.cs, Application_Start - prima di DoconutHost.Initialize.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Font errati o sostituiti — il server non dispone dei font del documento. Un Windows Server senza Office ha molti meno font rispetto a una macchina di sviluppo. Installa i font, o punta FontFolders (su WordConfig e PptConfig) a una cartella che li contiene.

Un'annotazione immagine appare nel visualizzatore ma l'esportazione mostra una casella "Immagine bloccata" — l'host dell'immagine ha un indirizzo privato o di loopback, che il server rifiuta di recuperare. Vedi Annotazioni.

La funzionalità funzionava in valutazione, silenziosa in produzione

Una licenza temporanea attiva concede tutte le capacità; la tua licenza acquistata concede solo ciò che hai comprato. Senza una capacità, i suoi file di Ricerca o Annotazione non vengono emessi, e un plugin registrato blocca il sito all'avvio. Confronta IsCapabilityGranted(...) con ogni funzionalità che utilizzi prima di distribuire.

La ricerca non trova nulla (o troppo poco)

Per un PDF, AllowSearch non era abilitato quando il documento è stato aperto — il valore predefinito è false. Word, Excel e PowerPoint espongono lo stesso interruttore.
Il contenuto è scansionato o solo immagine, quindi non c'è alcuno strato di testo da corrispondere.
HTML e Microsoft Project (MPP) non sono ricercabili con le impostazioni predefinite: imposta DefaultRender = false affinché vengano renderizzati tramite una proiezione PDF con testo.
objViewer.CanSearch() è false dopo l'inizializzazione: il formato risolto non ha percorso di ricerca. Questo è separato dalla licenza di Ricerca; controlla entrambi.
La pagina legge il valore di ritorno di objViewer.Search(...) — il conteggio arriva nel suo terzo argomento, una callback.

Ancora bloccato?

Riproduci il problema con la configurazione minima dalla Avvio rapido. Se si riproduce lì, contatta il supporto con il documento, il tuo Global.asax.cs, le parti Doconut di Web.config, e la voce del registro eventi di Windows se presente.