Visionneuse

Viewer (namespace Doconut) est le point d'entrée public pour ouvrir des documents depuis les pages Razor, les contrôleurs MVC, les composants Blazor ou les API minimalistes. Il est sealed, enregistré comme service transient par AddDoconut(), et résolu via l'injection de constructeur — ne le construisez jamais directement.

La bibliothèque .NET Standard précédente exposait un constructeur public prenant le cache mémoire, l'accès au contexte HTTP et un ou plusieurs chemins de licence. Ce constructeur a disparu ; le graphe de services fournit ces dépendances.

Viewer ne conserve aucun état par requête et ne pas implémente intentionnellement IDisposable : les sessions de documents vivent indépendamment dans le cache de session, de sorte que la suppression du service ne pourrait jamais fermer un document ouvert (voir Concepts de base → Comment la Visionneuse fonctionne).

OpenDocumentAsync

Ouvre un document et renvoie le jeton de session que le widget client utilise pour toutes les requêtes ultérieures. Chaque ouverture est asynchrone — il n'existe aucun OpenDocument synchrone.

// Ouverture simple
string token = await viewer.OpenDocumentAsync(path);

// Avec configuration et options par format
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Depuis un téléchargement
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Exceptions à gérer :

• LicenseException — une licence trouvée est rejetée (le message indique la raison du rejet), ou le format nécessite une capacité de plugin qui n'est plus accordée. L'expiration du calendrier sans message de rejet se traduit par un rendu filigrané au lieu de lever une exception.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — le contenu du fichier est corrompu ou ne correspond pas à son extension.

CloseDocument

void CloseDocument(string token)

Supprime la session du cache (en disposant immédiatement le moteur de document), supprime le marqueur de sécurité et révoque l'autorisation d'accès. Optionnel — l'expiration glissante effectue le même nettoyage — mais recommandé pour les gros documents.

GetPageCount

int GetPageCount(string token)

Nombre total de pages de la session ouverte. Lève une exception si le jeton est inconnu ou expiré.

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Renvoie les noms des feuilles de calcul d'une feuille de calcul ouverte, dans l'ordre du classeur, ou une liste vide lorsque le document ouvert n'est pas une feuille de calcul.

Seules les feuilles de calcul rendues sont listées : les feuilles cachées et vides sont exclues, et lorsque ExcelConfig.SheetNames restreint le rendu, seules ces feuilles apparaissent. Une feuille de calcul n'occupe pas toujours une seule page — une très grande est rendue sur plusieurs pages. Lève une exception si le jeton est inconnu ou expiré.

Ajouté dans la version 26.9.0.

Drapeaux de capacité

Utilisez‑les dans une vue Razor pour rendre un ruban sous licence uniquement lorsque le serveur le fournira réellement — voir Démarrage rapide.

DocOptions

Options indépendantes du format, par ouverture (espace de noms Doconut) :

La classe expose également des propriétés spécialisées qui sont intentionnellement en dehors du flux de visualisation normal à un seul hôte :

Filigrane personnalisé

DocOptions.Watermark utilise six champs séparés par des tildes. Un ^ optionnel en tête demande la disposition « tous les coins » :

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

L'analyseur attend exactement six champs après le ^ optionnel. Une définition invalide est remplacée par le fallback visible Invalid Watermark du SDK au lieu de disparaître silencieusement.

Décision de licence

La même décision s'applique aux images de pages servies et aux exportations d'annotations. La sortie GIF animée est marquée image par image. Un filigrane personnalisé est donc une fonctionnalité d'application sous licence, et non un moyen de remplacer ou de supprimer le filigrane d'évaluation.

API d'annotations

Chargement et export d'annotations côté serveur. Le guide complet se trouve dans Guides → Annotations ; l’interface est :

Chacun de ceux‑ci prend le jeton de session. La forme GetAnnotationManager(pageWidth, pageHeight) sans session de la bibliothèque précédente subsiste pour créer des annotations en dehors d’une session, mais leur chargement nécessite toujours un jeton.

Métadonnées DICOM

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

La méthode est présente pour l’alignement de l’API, mais ce paquet ne peut pas fournir les balises techniques DICOM : le lecteur de métadonnées n’est disponible qu’avec une version .NET 8. Il renvoie null pour les sessions DICOM et non‑DICOM ; sur une session DICOM il écrit également un avertissement unique expliquant la limitation de la plateforme. Le rendu des pages, des images‑cadres et des animations reste pris en charge.

Assistants de ressources — ReferenceCss / ReferenceScripts

Émettez les balises <link>/<script> pour les ressources intégrées servies par UseDoconutResources(), dans le bon ordre de dépendance. Les paquets pour les fonctionnalités soumises à licence, telles que la recherche et l’annotation, sont émis uniquement lorsque la licence les active, maintenant ainsi l’interface client cohérente avec le comportement du serveur.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + visualiseur + recherche + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig drapeaux : IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (déclenché par la recherche), IncludeAnnotationCss (déclenché par l’annotation).

ScriptConfig drapeaux : IncludeJQuery (requis par tous les autres), IncludeBootstrap, IncludeViewerScripts (noyau : docViewer.js + séparateur + liens), IncludeSearchScripts et IncludeSearchBar (déclenché par la recherche), IncludeAnnotationScripts et IncludeAnnotationBar (déclenché par l’annotation).

@inject Doconut.Viewer Viewer

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

Ces assistants sont la méthode prise en charge pour fournir les ressources du navigateur. Les applications qui ont copié docViewer.js, documentLinks.js et docViewer.UI.js dans wwwroot devraient supprimer ces copies une fois que la page est rendue à partir des balises émises.