Démarrage rapide
Rendez votre premier document en quelques minutes
Ce guide transforme une application ASP.NET Core d'un Program.cs vide en un document rendu dans le navigateur : enregistrement du serveur, le package complet du visualiseur (barre d'outils du visualiseur, montage du visualiseur et rubans de recherche/annotation optionnels), références d'actifs, initialisation du client, ouverture du document et exécution.
Configuration du serveur
AddDoconut() enregistre les services ; UseDoconutResources() et UseDoconut() connectent le middleware. L'appel aux ressources doit être le premier. UseDoconut() répond à chaque requête qui l'atteint, donc montez‑le sur sa propre branche avec app.Map. Les appels de session sont également requis — la sécurité documentaire par défaut de Doconut valide chaque requête de page contre l'état de session ASP.NET. L'état de session nécessite un cache : AddDistributedMemoryCache() en fournit un. Une application MVC ou Razor Pages l'enregistre déjà, mais une application minimal‑API ne le fait pas, et sans cela l'application s'arrête au démarrage avec Unable to resolve service for type 'IDistributedCache'. Vous avez déjà enregistré Doconut lors de Installation ? Passez à la section suivante.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // l'état de session nécessite un cache (MVC/Razor Pages en ajoute déjà un)
builder.Services.AddSession(); // La sécurité des documents Doconut repose sur l'état de session ASP.NET
app.UseSession(); // appelez UseSession() avant UseDoconut()
app.UseDoconutResources(); // doit être enregistré avant UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());Pour une structure de chemins de type production, mappez le middleware de document sur une branche explicite et maintenez les quatre paramètres de chemin alignés :
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
options.MiddlewarePath = "/doconut";
options.ResourcesPath = "/doconut-res";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());MiddlewarePath est une valeur de coordination ; elle ne mappe pas une branche ASP.NET Core à elle seule. Dans cet exemple, l'hôte mappe /doconut, ainsi le client utilise BasePath: 'doconut'. ResourcesPath sert le bundle intégré à /doconut-res, et le chemin de la ressource image du widget est donc ResPath: 'doconut-res/images'. Écrivez les deux sans slash initial : le visualiseur en ajoute un lui‑même, donc '/doconut' deviendrait //doconut/DocImage.axd, ce que le navigateur interprète comme une requête vers un hôte nommé doconut, et le visualiseur échoue avec « Le gestionnaire du visualiseur n'a pas pu être atteint ».
Ajouter le visualiseur à une page
Le visualiseur est le noyau requis de la page. Sa surface de rendu utilise deux div imbriqués :
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Considérez la barre d'outils, les montages de modules et la surface du visualiseur comme une seule composition de page. La recherche et l'annotation injectent leurs rubans intégrés dans des montages optionnels, mais ces modules ne sont jamais autonomes : ils s'attachent toujours au visualiseur sur la même page. Utilisez cet ordre :
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Boutons de navigation, zoom, recherche et annotation du visualiseur -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Référencer les ressources du visualiseur
Dans une vue Razor, le service Viewer injecté émet les balises <link> et <script> du visualiseur dans l'ordre de dépendance — le widget est un plugin jQuery, donc jQuery doit être chargé avant les scripts du visualiseur :
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
}))Pour le package complet du visualiseur, demandez le visualiseur et les ressources des modules ensemble :
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true,
IncludeSearchCss = true,
IncludeAnnotationCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true,
IncludeSearchScripts = true,
IncludeSearchBar = true,
IncludeAnnotationScripts = true,
IncludeAnnotationBar = true
}))IncludeViewerCss et IncludeViewerScripts sont les indicateurs de base obligatoires. Ne publiez jamais d'exemple de ruban recherche ou annotation sans eux, le montage du visualiseur et une docViewer instance. ReferenceCss et ReferenceScripts omettent les ressources d'un module optionnel lorsque la licence actuelle ne permet pas cette capacité ; le visualiseur de base démarre tout de même.
Initialiser le visualiseur
Le widget côté client est un plugin jQuery. Voici un ensemble minimal d'options d'initialisation réelles (et non du pseudocode) :
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // pas de '/' au début
ResPath: 'doconut-res/images', // pas de '/' au début
onViewerReady: function () {
// les pages sont visibles; il est sûr de masquer un indicateur de chargement ici
},
// Transférer les événements du cycle de vie des annotations vers le ruban intégré lorsqu'il est présent.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});La casse des options est réellement mixte — showThumbs, autoLoad et pageZoom sont en camelCase, mais FitType, BasePath et ResPath sont en PascalCase. Il n'existe aucune règle cohérente ; si la casse est incorrecte, l'option est silencieusement ignorée (le widget revient à sa valeur par défaut au lieu de lever une exception).
Quatre autres détails échouent sans message d'erreur :
BasePathn'a pas de slash initial.'doconut'demande/doconut/DocImage.axd;'/doconut'produit//doconut/DocImage.axd, que le navigateur interprète comme une requête vers un autre hôte.ResPath: 'doconut-res/images'— les icônes se trouvent un dossier en dessous de la racine des ressources. Avec'doconut-res', chaque icône renvoie 404 : aucun glyphe de barre d'outils et aucun indicateur de chargement, tandis que le document lui‑même s'affiche toujours. Un slash initial le casse de la même façon queBasePath.- Les callbacks sont des options.
onViewerReady,onErroret les autres doivent être placés dans l'objet passé àdocViewer(...). Une fonction globale nommée d'après le visualiseur, commectlDoc_ViewerReady, n'est jamais appelée. - Conservez le visualiseur, puis appelez
Viewséparément.docViewer(...)renvoie l'objet avecZoom,NextetFitType;View(...)renvoie autre chose.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)rend le document, puis échoue avecobjViewer.Zoom is not a functionau premier clic sur la barre d'outils.
Assembler le package complet du Viewer
Une page complète du visualiseur installe les parties suivantes ensemble :
| Partie du package | Exigence | Comment elle est connectée |
|---|---|---|
Ressources du Viewer, montage, et objViewer | Obligatoire | Moteur de rendu de document principal |
| Barre d'outils du Viewer | Obligatoire pour une page complète | Balise hôte ; les boutons appellent le même objViewer |
| Ruban de recherche | Optionnel, module sous licence | doconutSearchBar(...).attach(objViewer) |
| Ruban d'annotation | Optionnel, module sous licence | doconutAnnotationBar(...).attach(objViewer) |
Bien que la barre d'outils principale du Viewer soit du balisage hôte, elle est installée à côté du Viewer et ne doit jamais être documentée comme un contrôle isolé. Cela maintient sa disposition, ses libellés, ses icônes et ses règles d'autorisation sous le contrôle de votre application tandis que chaque bouton pilote la même instance du Viewer :
<nav id="toolbar" aria-label="Document viewer controls">
<button type="button" onclick="objViewer.GotoPage(1)">First</button>
<button type="button" onclick="objViewer.Next(false)">Previous</button>
<button type="button" onclick="objViewer.Next(true)">Next</button>
<button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
<button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
<button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
<button type="button" onclick="objViewer.FitType('width')">Fit width</button>
<button type="button" onclick="objViewer.FitType('height')">Fit height</button>
<button type="button" id="openSearch">Search</button>
<button type="button" id="openAnnotations">Annotations</button>
</nav>Les aides de rotation, vignette, impression, plein écran, mise en page et état des boutons doivent se trouver dans votre propre script de barre d'outils, qui appelle le même objViewer. Chargez‑le après Viewer.ReferenceScripts(...), et conservez‑le avec son balisage <nav id="toolbar">.
Conservez cet ordre d'initialisation :
- Émettre le CSS pour le Viewer et les modules sous licence.
- Rendre la barre d'outils du Viewer, les montages Recherche/Annotation, et le montage du Viewer ensemble.
- Émettre les scripts pour le Viewer et les modules sous licence.
- Charger le script d'aide de la barre d'outils propre à l'application hôte.
- Initialiser
docVieweret conserver leobjViewerrésultant. - Initialiser chaque ruban Recherche ou Annotation sous licence.
- Appeler
attach(objViewer)sur chaque ruban. - Ouvrir le document et conserver son jeton pour les requêtes du Viewer et des modules.
Dans un déploiement distribué, la valeur de requête supplémentaire access et les paramètres de nouvelle tentative de rendu asynchrone appartiennent au transport ; ils ne modifient pas la façon dont le Viewer, la barre d'outils ou les rubans sont assemblés.
Les garde‑fous côté serveur sont importants : lorsqu'une fonctionnalité optionnelle n'est pas disponible, son script n'est pas émis, de sorte que sa fonction de plug‑in jQuery n'existe pas.
<script>
let token = '';
const refitViewer = () =>
requestAnimationFrame(() => objViewer.Refit());
@if (Viewer.IsSearchEnabled)
{
<text>
searchBar = $('#searchBarMount').doconutSearchBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
searchBar.attach(objViewer);
</text>
}
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
annBar.attach(objViewer);
</text>
}
document.getElementById('openSearch').addEventListener('click', () => {
if (!searchBar) return;
searchBar.isOpen() ? searchBar.close() : searchBar.open();
});
document.getElementById('openAnnotations').addEventListener('click', () => {
if (!annBar) return;
annBar.isOpen() ? annBar.close() : annBar.open();
});
</script>Les deux composants embarqués génèrent leur propre DOM de ruban. La recherche contient les groupes Trouver, Options et Résultats. L'annotation contient ses outils d'édition, contrôles de style, actions d'enregistrement et actions d'exportation/image optionnelles. Les barres exposent open(), close(), reset() et isOpen() ; appelez toujours attach(objViewer) une fois après les avoir créées.
L'exemple ci‑dessus omet les callbacks hôte optionnels et les points de terminaison d'exportation/image d'Annotation afin de garder le démarrage minimal. Voir Recherche et Annotations pour la configuration complète spécifique aux fonctionnalités, ou Thèmes personnalisés pour styliser ou remplacer la barre d'outils du Viewer détenue par l'hôte.
Ouvrir un document
Le côté serveur est un seul point de terminaison : le service injecté Viewer ouvre le document et renvoie un jeton de session.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Le token est opaque — transmettez‑le au widget, ne le journalisez ni ne le persistez jamais.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});Le client récupère ce jeton et le transmet au widget avec objViewer.View(token) :
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Fermer le document
Appelez objViewer.Close(true) lorsque l'utilisateur quitte le visualiseur ou ouvre un document de remplacement : cela vide le widget et envoie une requête de fermeture au serveur. objViewer.Close() sans argument ne vide que le widget. Dans les flux de travail pilotés par le serveur, viewer.CloseDocument(token) supprime immédiatement la session en cache, libère le moteur de rendu, supprime son marqueur de sécurité et révoque le jeton. L'expiration glissante effectue finalement le même nettoyage, mais une fermeture explicite est recommandée pour les documents volumineux.
Le flux de requête complet est :
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentTraitez le jeton comme une information d'identification porteur : ne l'enregistrez jamais, ne le conservez jamais, remettez‑le uniquement au widget. Il identifie une session de document active sur le serveur et cesse de fonctionner lorsque cette session expire — rouvrez le document pour en obtenir un nouveau.
Lancer
Placez un PDF à wwwroot/files/Sample.pdf, exécutez dotnet run, et ouvrez la page qui héberge le widget. La première page s'affiche dans le visualiseur, avec un panneau de vignettes à gauche. Si ce n'est pas le cas, consultez Dépannage.
Ce que vous obtenez sans licence
Une licence manquante ne génère pas d'exception. Le visualiseur rend normalement, mais chaque page porte un filigrane d'évaluation. Consultez Configuration de licence pour savoir comment Doconut trouve une licence et ce qui change une fois qu'elle est trouvée.
Cette page était-elle utile ?