Doconut Viewer è una libreria .NET per la visualizzazione di documenti progettata per inserire PDF, Office, CAD, immagini e altre famiglie di documenti supportate all'interno di un'applicazione. Un'integrazione Doconut efficace riguarda meno il trovare lo snippet più breve e più la scelta di un confine pulito tra la tua applicazione, il visualizzatore e il browser.

Un'anteprima di documento incorporata disposta all'interno di uno spazio di lavoro strutturato di un'applicazione web

Il Doconut documentation hub collega ai percorsi di configurazione mantenuti per i tipi di progetto .NET supportati. Usa la guida che corrisponde alla versione installata nella tua applicazione, poi tratta la pagina circostante, i controlli di identità e il flusso di accesso come codice dell'applicazione di cui il tuo team è responsabile.

Inizia con il confine di integrazione

Esistono tre modi comuni per inserire un'anteprima di documento in un prodotto. La scelta giusta dipende da chi gestisce navigazione, autenticazione e ciclo di vita del visualizzatore.

Modello	Migliore adattamento	Principale compromesso
Vista dell'applicazione	Una pagina .NET che rende il visualizzatore accanto ai controlli del prodotto	Integrazione stretta, ma il ciclo di vita della pagina e del visualizzatore sono accoppiati
Iframe di proprietà dell'applicazione	Un portale che necessita di isolamento tra l'interfaccia host e il percorso di anteprima	Confine chiaro, ma la comunicazione deve essere progettata esplicitamente
Componente del framework attorno a una rotta server	Una shell React, Angular o Vue supportata da un'applicazione .NET	Composizione front-end familiare, con più stati del ciclo di vita da gestire

Il modello iframe non deve puntare a un URL di documento pubblico. Può puntare a una rotta autenticata nella tua stessa applicazione. Quella rotta può verificare l'accesso e rendere la pagina del visualizzatore senza esporre un percorso di archiviazione alla pagina host.

Costruisci una superficie di anteprima stabile e reattiva

Non ricostruire il markup o l'inizializzazione del visualizzatore da uno snippet illustrativo di un blog. Doconut pubblica i file, i passaggi middleware, gli spazi dei nomi e la configurazione del visualizzatore appropriati per ogni linea .NET supportata. Per esempio, la guida ufficiale di configurazione per .NET 6 o versioni successive spiega il middleware server, l'oggetto visualizzatore, le opzioni del documento, la configurazione di rendering e le risorse client richieste.

Usa quei materiali versionati per creare il visualizzatore, poi assegna alla sua regione host una larghezza e un'altezza stabili nel tuo layout. Riserva spazio sufficiente prima del caricamento affinché la pagina circostante non salti, e testa la barra degli strumenti e la prima pagina nei veri breakpoint supportati dal tuo prodotto.

Prima di impegnarti in una composizione, confrontala con le Doconut live demos ufficiali. Le demo coprono più stili di integrazione .NET e front‑end, includendo un esempio di iframe dedicato, e aiutano a distinguere un percorso supportato ufficialmente da uno snippet dall'aspetto plausibile.

Mantieni le decisioni di accesso sul server

La pagina host non dovrebbe mai decidere se un utente può visualizzare un documento. Prima di rendere la rotta di anteprima, l'applicazione dovrebbe:

Autenticare la richiesta.
Autorizzare l'utente per il documento richiesto e il tenant.
Risolvere il documento tramite un identificatore controllato dal server.
Aprirlo tramite il visualizzatore solo dopo che i controlli sono superati.
Restituire uno stato generico di non trovato o proibito senza rivelare dettagli di archiviazione.

Un identificatore opaco migliora l'igiene degli URL, ma non è autorizzazione. Applica gli stessi controlli a richieste di pagina, miniatura, ricerca, annotazione, esportazione e stampa che esponi.

Decidi come il host e il visualizzatore comunicano

Una vista dell'applicazione può chiamare direttamente i propri componenti. Un iframe richiede un contratto più ristretto. Definisci solo gli eventi di cui il host ha realmente bisogno, ad esempio:

Anteprima pronta
Documento non aperto
Pagina corrente cambiata
Sessione scaduta
Utente ha richiesto di chiudere l'anteprima

Se utilizzi postMessage, valida sia event.origin sia la forma del messaggio. Non accettare origini wildcard in produzione e non trasmettere mai credenziali, percorsi di archiviazione o contenuti grezzi del documento tramite messaggi.

Tratta le restrizioni del browser come difesa in profondità

Un iframe non è automaticamente isolato. Un attributo sandbox può ridurre le capacità, ma un valore eccessivamente restrittivo può anche rompere script del visualizzatore, download o comportamenti same‑origin. Parti dal più piccolo set di capacità documentato per la tua integrazione e testalo con la tua Content Security Policy.

Rivedi anche:

frame-ancestors o X-Frame-Options per la rotta di anteprima
frame-src per la pagina host
Comportamento dei cookie same-site se l'iframe richiede una sessione
Politica di referrer per gli URL che contengono identificatori di routing
Intestazioni di cache per le pagine che mostrano materiale sensibile

Questi controlli appartengono all'applicazione e all'infrastruttura circostanti. Un componente visualizzatore non può scegliere la politica corretta per la tua tenancy e modello di minaccia.

Progetta stati di caricamento, errore e scadenza

Un rettangolo vuoto non è un messaggio di errore utile. Fornisci alla pagina host stati espliciti per fallimento di autorizzazione, input non supportato, file danneggiati, timeout e sessioni scadute. Mantieni la formulazione azionabile senza rivelare percorsi interni o dettagli di eccezione.

Per documenti lunghi, conserva il contenitore del visualizzatore mentre la prima pagina è preparata. Se gli utenti possono cambiare documento senza lasciare la pagina, annulla le richieste obsolete e reimposta il titolo visibile, il conteggio delle pagine e il focus prima di caricare il prossimo elemento.

Accessibilità e comportamento della tastiera

Assegna a ogni iframe un title utile. Rendi l'anteprima raggiungibile da tastiera, fornisci un modo visibile per restituire il focus alla pagina host e non intrappolare il focus dentro overlay personalizzati. Se il visualizzatore ha proprie scorciatoie da tastiera, documenta i conflitti con le scorciatoie usate dalla tua shell di prodotto.

Un fallback accessibile può offrire un download controllato o una rappresentazione alternativa quando le regole di business lo consentono. Non aggiungere un collegamento a file pubblico solo come fallback.

Una checklist di verifica pratica

Prima del rilascio, verifica l'intero percorso di richiesta anziché solo il caricamento iniziale della pagina:

Un utente autorizzato può aprire un documento consentito.
Un utente di un altro tenant non può riutilizzare l'URL di anteprima.
Le richieste dirette agli endpoint relativi al visualizzatore ricevono gli stessi controlli di autorizzazione.
Aggiornamento, navigazione indietro e scadenza della sessione producono stati comprensibili.
L'anteprima rimane utilizzabile alle dimensioni del viewport e ai livelli di zoom supportati.
Gli errori della console del browser e le richieste di rete fallite sono visibili nel monitoraggio.
I log di archiviazione e dell'applicazione non registrano segreti o URL completi dei documenti.

Conclusione

L'embed Doconut più manutenibile è quello con un contratto piccolo ed esplicito. Lascia che Doconut gestisca il ruolo di visualizzazione dei documenti descritto nella sua documentazione versionata, mentre la tua applicazione possiede identità, autorizzazione, routing, conservazione, politica del browser e feedback utente. Quando sei pronto a valutare gli esempi confezionati localmente, utilizza le Doconut download resources ufficiali anziché copiare il codice sorgente da un articolo non correlato.