Visualiseur Doconut est une bibliothèque .NET de visualisation de documents conçue pour placer des PDF, Office, CAD, images et autres familles de documents prises en charge à l’intérieur d’une application. Une intégration Doconut solide porte moins sur la recherche du fragment le plus court et davantage sur le choix d’une frontière claire entre votre application, le visualiseur et le navigateur.
Le centre de documentation Doconut propose les chemins d’installation maintenus pour les types de projets .NET pris en charge. Utilisez le guide correspondant à la version installée dans votre application, puis considérez la page environnante, les vérifications d’identité et le flux d’accès comme du code d’application dont votre équipe est responsable.
Commencez par la frontière d’intégration
Il existe trois façons courantes de placer un aperçu de document dans un produit. Le bon choix dépend de qui possède la navigation, l’authentification et le cycle de vie du visualiseur.
| Modèle | Meilleur ajustement | Compromis principal |
|---|---|---|
| Vue d’application | Une page .NET qui rend le visualiseur à côté des contrôles du produit | Intégration étroite, mais la page et le cycle de vie du visualiseur sont couplés |
| Iframe détenu par l’application | Un portail qui nécessite une isolation entre l’interface hôte et la route d’aperçu | Frontière claire, mais la communication doit être conçue explicitement |
| Composant de framework autour d’une route serveur | Une coquille React, Angular ou Vue soutenue par une application .NET | Composition front‑end familière, avec davantage d’états de cycle de vie à gérer |
Le modèle iframe n’a pas besoin de pointer vers une URL de document publique. Il peut pointer vers une route authentifiée dans votre propre application. Cette route peut vérifier l’accès et rendre la page du visualiseur sans exposer le chemin de stockage à la page hôte.
Créez une surface d’aperçu stable et réactive
Ne reconstruisez pas le balisage ou l’initialisation du visualiseur à partir d’un extrait de blog illustratif. Doconut publie les fichiers, les étapes de middleware, les espaces de noms et la configuration du visualiseur appropriés à chaque branche .NET prise en charge. Par exemple, le guide d’installation officiel .NET 6 ou supérieur explique le middleware serveur, l’objet visualiseur, les options de document, la configuration de rendu et les actifs client requis.
Utilisez ces matériaux versionnés pour créer le visualiseur, puis attribuez à sa région hôte une largeur et une hauteur stables dans votre propre mise en page. Réservez suffisamment d’espace avant le chargement afin que la page environnante ne saute pas, et testez la barre d’outils ainsi que la première page aux points de rupture réels pris en charge par votre produit.
Avant de vous engager dans une composition, comparez‑la avec les démos en direct Doconut. Les démos couvrent plusieurs styles d’intégration .NET et front‑end, incluant un exemple d’iframe dédié, et aident à distinguer un chemin officiellement supporté d’un extrait qui semble plausible.
Conservez les décisions d’accès sur le serveur
La page hôte ne doit jamais décider si un utilisateur peut visualiser un document. Avant de rendre la route d’aperçu, l’application doit :
- Authentifier la requête.
- Autoriser l’utilisateur pour le document demandé et le locataire.
- Résoudre le document via un identifiant contrôlé par le serveur.
- L’ouvrir via le visualiseur uniquement après que ces vérifications aient réussi.
- Retourner un état générique « non trouvé » ou « interdit » sans divulguer les détails de stockage.
Un identifiant opaque améliore l’hygiène des URL, mais ce n’est pas une autorisation. Appliquez les mêmes vérifications aux requêtes de page, vignette, recherche, annotation, exportation et impression que vous exposez.
Décidez comment l’hôte et le visualiseur communiquent
Une vue d’application peut appeler ses propres composants directement. Un iframe nécessite un contrat plus restreint. Définissez uniquement les événements dont l’hôte a réellement besoin, tels que :
- Aperçu prêt
- Échec d’ouverture du document
- Page actuelle modifiée
- Session expirée
- L’utilisateur a demandé de fermer l’aperçu
Si vous utilisez postMessage, validez à la fois event.origin et la forme du message. N’acceptez pas d’origines génériques en production, et ne transmettez jamais d’identifiants, d’emplacements de stockage ou de contenu brut de document via les messages.
Traitez les restrictions du navigateur comme une défense en profondeur
Un iframe n’est pas automatiquement isolé. Un attribut sandbox peut réduire les capacités, mais une valeur trop stricte peut également casser les scripts du visualiseur, les téléchargements ou le comportement même‑origine. Commencez avec le plus petit ensemble de capacités documenté pour votre intégration et testez‑le avec votre politique de sécurité du contenu.
Passez également en revue :
frame-ancestorsouX-Frame-Optionspour la route d’aperçuframe-srcpour la page hôte- Comportement des cookies SameSite si l’iframe nécessite une session
- Politique de référent pour les URL contenant des identifiants de routage
- En‑têtes de cache pour les pages affichant du contenu sensible
Ces contrôles appartiennent à l’application et à l’infrastructure environnantes. Un composant visualiseur ne peut pas choisir la politique correcte pour votre locataire et votre modèle de menace.
Concevez les états de chargement, d’erreur et d’expiration
Un rectangle blanc n’est pas un message d’erreur utile. Fournissez à la page hôte des états explicites pour les échecs d’autorisation, les entrées non prises en charge, les fichiers endommagés, les délais d’attente et les sessions expirées. Gardez le libellé actionnable sans révéler les chemins internes ou les détails d’exception.
Pour les documents longs, conservez le conteneur du visualiseur pendant que la première page se prépare. Si les utilisateurs peuvent changer de document sans quitter la page, annulez les requêtes obsolètes et réinitialisez le titre visible, le nombre de pages et le focus avant de charger l’élément suivant.
Accessibilité et comportement du clavier
Attribuez à chaque iframe un title utile. Rendez l’aperçu accessible au clavier, fournissez un moyen visible de ramener le focus à la page hôte, et n’enfermez pas le focus dans des superpositions personnalisées. Si le visualiseur possède ses propres raccourcis clavier, documentez les conflits avec les raccourcis utilisés par votre coquille produit.
Une solution de secours accessible peut offrir un téléchargement contrôlé ou une représentation alternative lorsque vos règles métier le permettent. N’ajoutez pas de lien public vers un fichier uniquement comme solution de secours.
Liste de vérification pratique
Avant la mise en production, vérifiez le chemin complet de la requête et pas seulement le chargement initial de la page :
- Un utilisateur autorisé peut ouvrir un document autorisé.
- Un utilisateur d’un autre locataire ne peut pas réutiliser l’URL d’aperçu.
- Les requêtes directes aux points de terminaison liés au visualiseur reçoivent les mêmes vérifications d’autorisation.
- Le rafraîchissement, la navigation arrière et l’expiration de session produisent des états compréhensibles.
- L’aperçu reste utilisable aux tailles de fenêtre et niveaux de zoom pris en charge.
- Les erreurs de console du navigateur et les requêtes réseau échouées sont visibles dans la surveillance.
- Les journaux de stockage et d’application n’enregistrent pas de secrets ni d’URL complètes de documents.
Conclusion
L’intégration Doconut la plus maintenable est celle qui possède un contrat petit et explicite. Laissez Doconut gérer le rôle de visualisation de documents décrit dans sa documentation versionnée, tandis que votre application possède l’identité, l’autorisation, le routage, la rétention, la politique du navigateur et le retour utilisateur. Lorsque vous êtes prêt à évaluer les exemples fournis localement, utilisez les ressources de téléchargement Doconut plutôt que de copier le code source d’un article non lié.