Tutoriel : Ouvrir des documents avec le visualiseur Doconut injecté dans .NET 8

Introduction

Les exemples plus anciens de Doconut peuvent construire Viewer directement avec les arguments cache, HTTP-context et license-path. Ce n’est pas le modèle d’intégration actuel de .NET 8. AddDoconut() enregistre Viewer avec l’injection de dépendances, et les points de terminaison de l’application reçoivent le service au lieu d’appeler un constructeur.

Composants serveur abstraits transmettant un jeton de session opaque à une surface de visualisation de document

Ce tutoriel suit le flux de requête actuel : enregistrer les services et le middleware, émettre les ressources du visualiseur embarquées, ouvrir un document avec OpenDocumentAsync, renvoyer un jeton de session opaque et transmettre ce jeton au widget du navigateur.

1. Installer et enregistrer Doconut

Ajoutez le package .NET 8 :

dotnet add package Doconut.NET8

Enregistrez Doconut et les services de session ASP.NET :

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});

builder.Services.AddSession();

Branchez le middleware dans l’ordre requis. Le middleware de ressources doit s’exécuter avant le middleware terminal de document :

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath coordonne la configuration mais ne crée pas la branche ASP.NET à lui seul. Le chemin mappé /doconut doit correspondre au BasePath du widget.

2. Ajouter la surface du visualiseur et les ressources

Le visualiseur navigateur Doconut est un plugin jQuery. Dans une page Razor, injectez Viewer et demandez‑lui d’émettre les balises de ressources dans l’ordre de dépendance :

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery = true,
    IncludeViewerScripts = true
}))

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Initialisez le widget avec des chemins qui correspondent à l’enregistrement côté serveur :

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    pageZoom: 100,
    FitType: 'width',
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

La casse des options est importante. Utilisez les noms affichés par la version installée au lieu de les normaliser dans un style unique.

3. Injecter Viewer et ouvrir un document

Viewer est enregistré comme service transitoire. Résolvez‑le via l’injection de point de terminaison, l’injection de constructeur ou la facilité équivalente dans votre application ASP.NET Core.

app.MapPost("/api/open", async (
    Viewer viewer,
    CancellationToken ct) =>
{
    string token = await viewer.OpenDocumentAsync(
        "wwwroot/files/Sample.pdf",
        ct: ct);

    return Results.Ok(new { token });
});

Pour un téléchargement, fournissez un flux et un FileInfo dont l’extension identifie le format source :

app.MapPost("/api/open-upload", async (
    IFormFile file,
    Viewer viewer,
    CancellationToken ct) =>
{
    await using var stream = file.OpenReadStream();
    string token = await viewer.OpenDocumentAsync(
        stream,
        new FileInfo(file.FileName),
        ct: ct);

    return Results.Ok(new { token });
});

Validez la taille du téléchargement, l’extension et l’autorisation avant d’ouvrir le contenu fourni par l’utilisateur. Ne transformez pas le nom de fichier soumis en chemin serveur.

Récupérez le point de terminaison d’ouverture et transmettez le jeton retourné à objViewer.View :

fetch('/api/open', { method: 'POST' })
    .then(response => {
        if (!response.ok) throw new Error('The document could not be opened.');
        return response.json();
    })
    .then(data => objViewer.View(data.token))
    .catch(error => console.error(error));

Traitez le jeton comme un credential porteur pour une session de document en direct :

Ne le consignez pas et ne le stockez pas.
Ne le renvoyez qu’à un client autorisé.
Ne divulguez pas le chemin du fichier source.
Rouvrez le document lorsqu’une session expire.
Fermez la session lorsque le document n’est plus nécessaire.

5. Fermer délibérément les sessions côté serveur

Le code client peut appeler objViewer.Close() lorsque l’utilisateur quitte le visualiseur. Les flux de travail serveur peuvent également révoquer explicitement un jeton connu :

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

La fermeture explicite est particulièrement utile pour les gros documents. L’expiration de session reste une solution de secours, pas un substitut à une gestion prévisible du cycle de vie de l’application.

6. Ajouter des modules optionnels uniquement après le fonctionnement du cœur

La recherche et les annotations s’attachent au même visualiseur initialisé. Ajoutez leurs CSS, scripts, montages, vérifications de licence et callbacks de cycle de vie uniquement après la réussite du flux de base :

AddDoconut + session services
    -> UseSession
    -> UseDoconutResources
    -> mapped UseDoconut branch
    -> viewer resources and mount
    -> initialize docViewer
    -> OpenDocumentAsync
    -> objViewer.View(token)

Cet ordre maintient les échecs de rendu du cœur séparés de la configuration des modules optionnels.

Erreurs courantes de migration

Ancien ou mauvais modèle	Direction actuelle .NET 8
`new Viewer(cache, accessor, licensePath)`	Injecter `Viewer` après `AddDoconut()`
Appels statiques de chargement de licence dans le code de requête	Configurer l’entrée de licence dans `AddDoconut()`
Exemples synchrones `OpenDocument(...)`	Utiliser `OpenDocumentAsync(...)`
Un CDN externe ou inventé pour le visualiseur	Émettre les ressources embarquées avec `ReferenceCss` et `ReferenceScripts`
API JavaScript générique `init()`	Initialiser `$('#div_ctlDoc').docViewer(...)`
Persistance du jeton du visualiseur	Persister votre ID de document ; traiter le jeton comme temporaire

Utilisez la documentation Doconut officielle et vérifiez les exemples par rapport à la version du package installé avant de les adapter à du code de production.