Come funziona il Viewer

Il ciclo di vita della richiesta del documento

Doconut rende i documenti come immagini paginate, servite da un handler HTTP che il tuo Web.config registra. Comprendere il ciclo di vita — apertura, token, richieste di pagina, chiusura — spiega quasi tutti i comportamenti che osserverai, inclusi i messaggi di errore.

Le parti in movimento

  • Viewer — il servizio pubblico che risolvi da DoconutHost.Services. Apre i documenti e restituisce token di sessione.
  • La sessione del documento — un oggetto lato server che contiene il documento caricato, mantenuto in memoria sotto il suo token.
  • DocImage.axd — il Doconut.DocImageHandler dichiarato in Web.config. Risponde a ogni richiesta che il widget del browser effettua (pagine, miniature, ricerca, annotazioni, …), sempre identificato dal token.
  • /doconut-res/* — il Doconut.DoconutResourceModule, che serve gli script, gli stili e le icone del widget.

Viewer è senza stato — per progettazione

Viewer non mantiene alcuno stato del documento per richiesta e non implementa IDisposable. Le sessioni vivono indipendentemente da esso e vengono pulite tramite scadenza o un CloseDocument(token) esplicito. System.Web non ha iniezione tramite costruttore, quindi risolvilo dove ti serve — tipicamente in un'azione del controller:

csharp
// POST /ViewerApi/Open?fileName=Sample.pdf
[HttpPost]
public async Task<ActionResult> Open(string fileName)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    var path   = Server.MapPath("~/files/" + Path.GetFileName(fileName));

    var token = await viewer.OpenDocumentAsync(path);
    return Content(token, "text/plain");
}

Cosa succede all'interno di OpenDocumentAsync

  1. Porta di licenza. Una licenza rifiutata (manomessa, nella lista nera, o una build al di fuori della finestra di aggiornamento della licenza) lancia LicenseException immediatamente, con il motivo come messaggio. L'apertura non degrada mai silenziosamente per una licenza non valida; una licenza mancante aggiunge solo una filigrana.
  2. Creazione della sessione. La factory del visualizzatore sceglie il visualizzatore di formato per l'estensione del file e carica il documento (vedi Rendering Pipeline). La sessione è memorizzata in memoria sotto un nuovo token casuale con una scadenza scorrevole di DocOptions.TimeOut minuti (predefinito 60). Ogni richiesta di pagina resetta il timer.
  3. Concessione di accesso. Con UnsafeMode = false (il valore predefinito), il token è legato alla sessione ASP.NET della richiesta che l'ha aperto: una voce secure-{token} è scritta in quella sessione. L'apertura deve quindi avvenire in una richiesta con stato di sessione — vedi Sessions & Security.
  4. Il token viene restituito. È l'unico identificatore di cui il browser ha bisogno per tutto ciò che segue.

Le sovraccariche asincrone accettano un percorso file, un percorso file più una configurazione per formato (PdfConfig, WordConfig, …), o un Stream più un FileInfo la cui estensione seleziona il formato. Per il code-behind di Web Forms che non utilizza pagine asincrone, OpenDocument offre gli stessi tre input in modo sincrono (un percorso, uno stream con un nome file, o un array di byte con un nome file).

Come il widget ottiene le pagine

Il widget chiama DocImage.axd con il token nella stringa di query. Ciò che fa l'handler dipende dalla richiesta:

InterrogazioneScopo
?token=…&page=NImmagine della pagina renderizzata (PNG)
?token=…&page=N&thumb=1Miniatura
?token=…&zoom=…Rendering della pagina ingrandita
?token=…&search=termRicerca full-text (con licenza)
?token=…&bookmarksStruttura del documento e segnalibri
?token=…&copy / &showlinks / &fileFormatCopia del testo, collegamenti ipertestuali e informazioni di formato
?token=…&metaMetadati tecnici DICOM — non disponibili in questo pacchetto (risponde 404)
?token=…&action=rotate/flip/closeAzioni della pagina e chiusura esplicita (POST)
?token=…&AnnSave=… / &AnnLoadSalva e carica annotazioni

Ogni richiesta è verificata prima:

  • Nessun token → 404, o un banner di versione quando ShowDoconutInfo = true.
  • Token non concesso a questa sessione ASP.NET → un'immagine di errore con il testo You Are Not Authorized To View This Page.
  • Token sconosciuto o scaduto → un'immagine di errore con il testo Document session not found. Please re-open document.

Le immagini di errore sono PNG ordinari inviati con stato 200, così il widget può mostrarle al posto della pagina. Un controllo di monitoraggio che guarda solo il codice di stato le segnalerà come pagine servite; una pagina reale è di decine‑centinaia di kilobyte, un'immagine di errore circa 2 KB.

Chiusura di un documento

csharp
viewer.CloseDocument(token);

CloseDocument rimuove la sessione (rilasciando immediatamente il motore del documento e la sua memoria), rimuove la voce secure-{token} dalla sessione ASP.NET della richiesta corrente, e revoca il token. È opzionale — la scadenza scorrevole fa la stessa pulizia — ma per documenti grandi libera la memoria non appena l'utente ha finito. Dal browser, objViewer.Close(true) invia la richiesta di chiusura equivalente a DocImage.axd.

Conclusioni

  • Un documento aperto = una sessione = un token, concesso alla sessione ASP.NET che lo ha aperto.
  • Il token scade su una finestra scorrevole; un visualizzatore lasciato inattivo oltre DocOptions.TimeOut necessita di una riapertura.
  • Viewer può essere risolto e condiviso liberamente; le sessioni trasportano tutto lo stato.

Questa pagina è stata utile?