Visionneuse
La classe principale du visualiseur de documents
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 un 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 graph de services fournit ces dépendances.
Viewer ne conserve aucun état par requête et ne implémente pas 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 fonctionne le Viewer).
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.
| Surcharge | Quand utiliser |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Ouverture depuis le disque avec détection automatique du format et la configuration par défaut du format |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Vous avez besoin d'options de rendu par format (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Le document n'est pas un fichier sur le disque (téléversement, base de données, blob). fileInfo doit contenir la bonne extension — elle détermine la détection du format |
// Ouverture simple
string token = await viewer.OpenDocumentAsync(path);
// Avec une configuration et des 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 InvalidOperationException (Document session not found. Please re-open document.) si le jeton est inconnu ou expiré, et ArgumentException pour un jeton vide.
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)Taille de page rendue par défaut du document à 100 % de zoom — l'espace de coordonnées pour les annotations générées en code. page est accepté pour la compatibilité ; le résultat est la valeur par défaut du document. Lève InvalidOperationException (Document session not found. Please re-open document.) si le jeton est inconnu ou expiré, et ArgumentException pour un jeton vide.
Obtenir les noms des feuilles de calcul
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 répertorié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 InvalidOperationException (Document session not found. Please re-open document.) si le jeton est inconnu ou expiré, et ArgumentException pour un jeton vide.
Ajouté dans la version 26.9.0.
Indicateurs de capacité
| Membre | Signification |
|---|---|
bool IsSearchEnabled | La licence actuelle accorde Search |
bool IsAnnotationEnabled | La licence actuelle accorde Annotation |
Utilisez‑les dans une vue Razor pour rendre un ruban sous licence uniquement lorsque le serveur le fournira réellement — voir Démarrage rapide.
Options de document
Options indépendantes du format, par ouverture (espace de noms Doconut) :
| Type | Propriété | Valeur par défaut | Description |
|---|---|---|---|
string | Password | "" | Mot de passe pour les documents protégés (copié automatiquement dans la configuration du format). |
int | ImageResolution | 0 | Obsolète. Conserve uniquement pour la compatibilité — définissez ImageResolution sur la configuration du format à la place. |
string | Watermark | "" | Texte de filigrane personnalisé dessiné sur les pages rendues. Chaîne de format : "^Text~Color~FontSize~FontName~Opacity~Angle", par ex. "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | Expiration glissante de la session en minutes. |
bool | IsSecured | true | Pas actuellement appliqué — réservé. La liaison du jeton est contrôlée globalement par DoconutOptions.UnsafeMode (voir Concepts de base → Sessions & Sécurité). |
La classe expose également des propriétés spécialisées qui se trouvent intentionnellement en dehors du flux de visualisation normal à un seul hôte :
| Type | Propriété | Valeur par défaut | Description |
|---|---|---|---|
bool | IsWebFarm | false | Obsolète — n'a aucun effet. Publiez le document avec DistributedDocumentPublisher.PublishAsync (ou IDistributedPublishQueue.EnqueueAsync) et définissez FileShareConfig.RootPath à la place. Notez la casse — la bibliothèque précédente orthographiait cela IsWebfarm. |
string | WebFarmPath | "" | Obsolète — n'a aucun effet. Utilisez FileShareConfig.RootPath, comme décrit dans Déploiements distribués. Orthographié auparavant WebfarmPath. |
bool | EditMode | false | Réservé à un flux de travail d'édition distribué séparément ; laissez false pour le visualiseur standard. |
Filigrane personnalisé
DocOptions.Watermark utilise six champs séparés par des tildes. Un ^ optionnel en tête demande la disposition sur tous les coins :
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Champ | Exemple | Signification |
|---|---|---|
Préfixe ^ | ^ | Mise en page sur tous les coins optionnelle. Sans cela, le placement normal du filigrane est utilisé. |
| Text | Confidential | Texte rendu sur chaque page. Il ne doit pas être vide. |
| Color | Red | Couleur nommée reconnue par la couche de dessin. |
| FontSize | 24 | Taille de police ; une entrée numérique invalide revient à la valeur par défaut du rendu. |
| FontName | Verdana | Famille de police demandée. Assurez‑vous qu'elle est installée dans l'environnement de déploiement. |
| Opacity | 80 | Valeur d'octet de 0 à 255. Elle doit être analysée avec succès. |
| Angle | -45 | Angle de rotation en degrés ; une entrée numérique invalide revient à la valeur par défaut. |
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
| État de la licence | Valeur personnalisée fournie | Résultat rendu |
|---|---|---|
| Licence de visualisation payante valide | Non | Page propre |
| Licence de visualisation payante valide | Oui | Filigrane personnalisé |
| Visualiseur de base temporaire/démo actif | Non | Page du visualiseur de base propre |
| Visualiseur de base temporaire/démo actif | Oui | Filigrane personnalisé lorsque le chemin du visualiseur de base propre s'applique |
| Licence manquante, rejetée, expirée, de mauvaise version ou de domaine invalide | Quelconque | Filigrane d'application/évaluation ; la valeur personnalisée ne le remplace pas |
| Rendu du plugin selon les règles d'évaluation | Quelconque | Filigrane d'évaluation |
La même décision s'applique aux images de pages servies et aux exportations d'annotations. La sortie GIF animée est estampillé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 des annotations
Chargement et exportation d'annotations côté serveur. Le guide complet se trouve dans Guides → Annotations ; l'interface est :
| Membre | Objectif |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Gestionnaire lié aux dimensions de page de la session ouverte |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Gestionnaire avec dimensions de page explicites |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Gestionnaire indépendant de la session |
void LoadAnnotationData(string token, AnnotationManager manager) | Charger les annotations créées en C# dans la session |
void LoadAnnotationData(string token, string annotationData) | Charger les annotations depuis la page encodée/enveloppe Base64 renvoyée par AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Charger les annotations depuis XML |
XmlDocument GetAnnotationXML(string token) | Exporter les annotations de la session au format XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF avec annotations intégrées |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Un PNG par page, annotations intégrées, écrit dans directoryPath (créé si absent) ; renvoie le nombre d'images écrites |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP de PNGs par page avec annotations intégrées |
Chaque fonction prend le jeton de session. La forme sans session GetAnnotationManager(pageWidth, pageHeight) 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'en version .NET 8. Il renvoie null pour les sessions DICOM et non‑DICOM ; lors d'une session DICOM, il écrit également un avertissement unique expliquant la limitation de la plateforme. Le rendu de pages, de cadres et d'animations reste pris en charge.
Assistants de ressources — ReferenceCss / ReferenceScripts
Émettre les balises <link>/<script> pour les ressources intégrées servies par UseDoconutResources(), dans l'ordre de dépendance correct. Les paquets pour les fonctionnalités soumises à licence, comme 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 (cœur : docViewer.js + séparateur + liens), IncludeSearchScripts et IncludeSearchBar (déclenché par la recherche), IncludeAnnotationScripts et IncludeAnnotationBar (déclenché par l'annotation), EmitFeatureFlags (par défaut true : écrit également un script inline window.Doconut.features = { search, annotation, editor } ; définissez‑le à false sous une Content‑Security‑Policy qui bloque les scripts inline).
@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 la page rendue à partir des balises émises.
Cette page était-elle utile ?