Implementare la Gestione Documenti con Doconut

Un flusso di gestione documenti in un portale .NET solitamente richiede tre cose:

1. Un modo per caricare PDF, file Office, disegni CAD o immagini senza dover scrivere un visualizzatore da zero.
2. Un token sicuro che collega il documento caricato alla sessione del browser corrente.
3. Un passaggio di pulizia che libera la memoria non appena l'utente ha finito.

Doconut fornisce tutti e tre tramite un unico servizio Viewer, una sessione IMemoryCache leggera e chiamate esplicite CloseDocument.

---

1. Registrare il visualizzatore nel contenitore DI

Durante l'avvio dell'applicazione, aggiungi i servizi Doconut al contenitore DI chiamando il metodo di registrazione Doconut descritto nella documentazione ufficiale. Questo passaggio registra il visualizzatore, la gestione della licenza e la cache in‑memory che conterrà le sessioni dei documenti.

La registrazione valida la licenza all'avvio, così qualsiasi licenza mancante o non valida fallisce immediatamente e conosci il problema prima che la prima richiesta raggiunga il server.

---

2. Inserire il middleware che serve immagini di pagina, miniature e dati di annotazione

Configura il middleware Doconut nella pipeline di richiesta in modo che qualsiasi richiesta contenente una stringa di query ?token= sia gestita da Doconut. Il middleware applica il marcatore di sicurezza predefinito (secure-{token}) quando UnsafeMode è false (il valore predefinito) e serve immagini di pagina, miniature e dati di annotazione.

Posizionare il middleware su un ramo dedicato mantiene intatta il resto della tua pipeline e consente il ridimensionamento orizzontale senza sessioni sticky.

---

3. Aprire un documento e ottenere il token di sessione opaco

Crea un unico endpoint che riceve un percorso file (o uno stream) e restituisce il token. Il token è l'unica credenziale che il widget client vede.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Il token è opaco — passalo al widget, non registrarlo né conservarlo.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

Cosa succede all'interno di OpenDocumentAsync

1. Gate della licenza – una licenza non valida genera LicenseException immediatamente.
2. Creazione della sessione – Doconut seleziona il visualizzatore del formato corretto (PDF, Word, DWG, …) e memorizza il motore in IMemoryCache sotto un token GUID.
3. Registrazione della sicurezza – con UnsafeMode = false il token è legato alla sessione ASP.NET del chiamante tramite un marcatore secure-{token}. Solo quella sessione del browser può richiedere le pagine.
4. Restituzione del token – il client riceve il token e lo utilizza per ogni successiva richiesta (/DocImage.axd?token=…).

La scadenza scorrevole predefinita è di 60 minuti (configurabile tramite DocOptions.TimeOut). Ogni richiesta di pagina resetta il timer, così le sessioni inattive scompaiono automaticamente.

---

4. Renderizzare il documento sul lato client

Dal browser chiami l'endpoint, ottieni il token e lo passi al widget Doconut:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // JavaScript widget fornito da Doconut
    });

Il widget internamente invia richieste di pagina, miniature, ricerca e annotazione che includono tutte lo stesso token. Poiché il token è legato alla sessione lato server, un utente malintenzionato non può dirottare il documento di un altro utente.

---

5. Chiudere il documento non appena l'utente lascia il visualizzatore

Per PDF o file CAD di grandi dimensioni dovresti rilasciare immediatamente il motore di rendering. Chiama CloseDocument da un endpoint lato server o dall'evento “unload” del widget.

// Endpoint lato server
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// Chiamata diretta dal widget (se esponi il token al backend)
viewer.CloseDocument(token);

CloseDocument rimuove la sessione dalla cache, elimina il motore del documento sottostante, cancella il marcatore secure-{token} e revoca il permesso di accesso. La scadenza scorrevole farebbe lo stesso alla fine, ma una chiusura esplicita garantisce che la memoria venga recuperata subito quando l'utente ha finito.

---

6. Opzionale: Convertire un documento sul server

Se il tuo flusso di lavoro richiede un'esportazione PDF di un file Word caricato, abilita il plugin Converter nella configurazione Doconut (vedi documentazione). Dopo che il plugin è registrato puoi iniettare DocumentConverter e chiamare il suo metodo ConvertAsync. La conversione avviene sul server, quindi non avrai mai bisogno di Office installato sul server web.

---

7. Considerazioni di scalabilità per la gestione documenti di livello enterprise

• Front‑end senza stato – Il widget del visualizzatore non contiene mai dati del documento; tutta l'elaborazione pesante rimane sul server.
• Cache distribuita – Sostituisci la cache in‑memory predefinita con un provider distribuito (Redis, NCache) se utilizzi più nodi web‑farm. La mappatura token‑sessione funziona invariata perché il middleware legge dal IMemoryCache configurato.
• Job in background – Puoi pre‑aprire documenti in un worker in background, memorizzare il token nella cache e passarne l'uso all'interfaccia più tardi. Ricorda solo che ogni token è monouso per sessione; riutilizzarlo richiede una nuova chiamata OpenDocumentAsync.

Questi pattern ti permettono di costruire una piattaforma di gestione documenti che scala da un portale intranet a singolo server a un servizio cloud multi‑regione senza riscrivere la logica del visualizzatore.

---

8. Checklist rapido per un'implementazione pronta per la produzione

Passo	Azione
1	Registra i servizi Doconut in Program.cs (valida la licenza).
2	Aggiungi il middleware Doconut su un ramo dedicato.
3	Esporre un endpoint /api/open che chiama OpenDocumentAsync.
4	Passa il token restituito a objViewer.View(token) nel client.
5	Chiama CloseDocument(token) quando il visualizzatore è nascosto o la pagina si scarica.
6	(Opzionale) Abilita ConverterPlugin se hai bisogno di conversione lato server.
7	(Opzionale) Sostituisci IMemoryCache con una cache distribuita per il ridimensionamento orizzontale.

Segui l'elenco, e avrai un flusso completo, sicuro e ad alte prestazioni di gestione documenti costruito sul visualizzatore .NET nativo di Doconut.