Come funziona il Viewer
Il ciclo di vita della richiesta del documento
Doconut rende i documenti come immagini paginate servite tramite middleware ASP.NET Core. Comprendere il ciclo di vita — apertura, token, richieste di pagina, chiusura — spiega quasi tutti i comportamenti che osserverai, inclusi i messaggi di errore.
I tre componenti in movimento
Viewer— il servizio pubblico che inietti. Apre i documenti e restituisce token di sessione.- La sessione del documento — un oggetto lato server che contiene il documento caricato, indicizzato da un token in
IMemoryCache. - Il middleware Doconut — aggiunto da
UseDoconut(); risponde a ogni richiesta che il widget del browser effettua (pages,thumbnails,search,annotations, …), sempre autenticato dal token.
Viewer è senza stato — per progettazione
Viewer è sealed, non mantiene alcuno stato del documento per richiesta, e deliberatamente non implementa IDisposable. Le sessioni vivono indipendentemente nel gestore delle sessioni e vengono pulite tramite scadenza della cache o un CloseDocument(token) esplicito.
Iniettalo ovunque ne hai bisogno:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});Cosa succede all'interno di OpenDocumentAsync
- License gate. Una licenza rifiutata o scaduta per versione (in blacklist, manomessa, o una build al di fuori della finestra di aggiornamento della licenza) genera immediatamente un
LicenseException, con il motivo del rifiuto come messaggio — l'apertura non degrada mai silenziosamente per una licenza non valida (invece che assente). Una licenza Temporanea o di abbonamento scaduta per calendario è l'eccezione: non genera eccezione — degrada a filigrana. - Session creation. La factory del viewer sceglie il visualizzatore di formato corretto per l'estensione del file e carica il documento (vedi Rendering Pipeline). La sessione è memorizzata in
IMemoryCachesotto un nuovo token GUID con una scadenza scorrevole —DocOptions.TimeOutminuti, default 60. Ogni richiesta di pagina resetta il timer. - Security registration. Con
UnsafeMode = false(il valore predefinito), il token è legato alla sessione ASP.NET del chiamante: un marcatoresecure-{token}è scritto nella sessione, così solo la sessione del browser che ha aperto il documento può richiedere le sue pagine. - Il token viene restituito. È l'unica credenziale per tutto ciò che segue.
Le tre sovraccarichi differiscono solo nell'input: un percorso file, un percorso file più una configurazione per formato (PdfConfig, WordConfig, …), o un Stream più un FileInfo la cui estensione determina il rilevamento del formato.
Come il widget ottiene le pagine
Il widget client chiama il middleware Doconut con il token nella stringa di query. Ciò che fa il middleware dipende dalla richiesta:
| Query | Scopo |
|---|---|
?token=…&page=N | Immagine della pagina renderizzata (PNG) |
?token=…&page=N&thumb=1 | Miniatura |
?token=…&zoom=… | Rendering della pagina ingrandita |
?token=…&search=term | Ricerca full-text (con licenza) |
?token=…&bookmarks | Struttura del documento / segnalibri |
?token=…© / &showlinks / &fileFormat / &meta | Copia del testo, collegamenti ipertestuali, informazioni sul formato, metadati tecnici DICOM |
?token=…&action=rotate/flip/close | Azioni della pagina e chiusura esplicita |
?token=…&AnnSave=… / &AnnLoad | Salva/carica annotazioni |
Ognuno di questi percorsi viene validato prima:
- No token → il middleware restituisce 404 (o un banner di versione quando
ShowDoconutInfo = true). - Unknown or expired token → un'immagine di errore con
Document session not found. Please re-open document. - Session middleware missing (con
UnsafeMode = false) → HTTP 500 conSession middleware not configured. Call UseSession() before UseDoconut(). - Token opened by a different browser session → un'immagine di errore con
You Are Not Authorized To View This Page.
Servire le pagine da storage condiviso invece del nodo di apertura è un'organizzazione completamente diversa; vedi Distribuzioni distribuite.
Chiusura di un documento
viewer.CloseDocument(token);CloseDocument rimuove la sessione dalla cache (che elimina il motore del documento sottostante e libera immediatamente la sua memoria), elimina il marcatore secure-{token}, e revoca il permesso di accesso. Chiamarlo è opzionale — la scadenza scorrevole esegue la stessa pulizia automaticamente — ma per documenti di grandi dimensioni è il modo cortese di rilasciare la memoria non appena l'utente ha finito.
Conclusioni
- Un documento aperto = una sessione = un token. I token sono per sessione del browser, non URL globali.
- Il token scade su una finestra scorrevole; un viewer lasciato inattivo oltre
DocOptions.TimeOutnecessita di una riapertura. Viewerpuò essere iniettato e condiviso liberamente; le sessioni contengono tutto lo stato.
Questa pagina è stata utile?