Come funziona il Viewer

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 principali

• 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 autenticata dal token.

Viewer è senza stato — per design

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 dalla scadenza della cache o da un esplicito CloseDocument(token).

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

1. Gate della licenza. Una licenza rifiutata o scaduta per versione (in blacklist, manomessa, o una build al di fuori della finestra di aggiornamento della licenza) genera immediatamente una LicenseException, con il motivo del rifiuto come messaggio — l'apertura non degrada mai silenziosamente per una licenza non valida (a differenza di una assente). Una licenza Temporanea o di abbonamento scaduta per calendario è l'eccezione: non genera eccezione — degrada a filigrana.
2. Creazione della sessione. La factory del viewer seleziona il viewer di formato corretto per l'estensione del file e carica il documento (vedi Rendering Pipeline). La sessione è memorizzata in IMemoryCache sotto un nuovo token GUID con una scadenza scorrevole — DocOptions.TimeOut minuti, default 60. Ogni richiesta di pagina resetta il timer.
3. Registrazione della sicurezza. Con UnsafeMode = false (impostazione predefinita), il token è legato alla sessione ASP.NET del chiamante: un marcatore secure-{token} è scritto nella sessione, così solo la sessione del browser che ha aperto il documento può richiedere le sue pagine.
4. Il token viene restituito. È l'unica credenziale per tutto ciò che segue.

Le tre overload differiscono solo nell'input: un percorso file, un percorso file più una configurazione per formato (PdfConfig, WordConfig, …), o uno 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 il middleware fa dipende dalla richiesta:

Ognuno di questi percorsi viene prima validato:

• Nessun token → il middleware restituisce 404 (o un banner di versione quando ShowDoconutInfo = true).
• Token sconosciuto o scaduto → un'immagine di errore con Sessione documento non trovata. Per favore riapri il documento.
• Middleware di sessione mancante (con UnsafeMode = false) → HTTP 500 con Middleware di sessione non configurato. Chiama UseSession() prima di UseDoconut().
• Token aperto da una sessione browser diversa → un'immagine di errore con Non sei autorizzato a visualizzare questa pagina.

Chiudere un documento

viewer.CloseDocument(token);

CloseDocument rimuove la sessione dalla cache (che dispone 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 corretto per rilasciare la memoria non appena l'utente ha finito.

Punti chiave

• Un documento aperto = una sessione = un token. I token sono per sessione browser, non URL globali.
• Il token scade su una finestra scorrevole; un viewer inattivo oltre DocOptions.TimeOut necessita di una riapertura.
• Viewer può essere iniettato e condiviso liberamente; le sessioni contengono tutto lo stato.