Visionneuse
La classe principale du visionneur de documents
Viewer (namespace Doconut) est le point d'entrée public pour ouvrir des documents depuis les contrôleurs MVC, les pages Web Forms et les gestionnaires. C'est un service transient composé par DoconutHost.Initialize ; résolvez‑le là où vous l'utilisez :
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() fonctionne également une fois que DoconutHost.Initialize a été exécuté — il résout les mêmes services — ce qui permet au code migré depuis le package classique de se compiler. Avant Initialize, il lève InvalidOperationException.
Viewer ne conserve aucun état de document par requête et intentionnellement ne pas implémente IDisposable : les sessions de documents vivent indépendamment de lui, ainsi la suppression d'un Viewer ne pourra jamais fermer un document ouvert (voir Comment le Visionneur Fonctionne).
OpenDocumentAsync
Ouvre un document et renvoie le jeton de session que le widget utilise pour chaque requête ultérieure. Lorsque UnsafeMode est false (par défaut), le jeton est accordé à la session ASP.NET de la requête en cours — appelez‑le depuis une requête disposant d'un état de session (voir Sessions et Sécurité).
| Surcharge | Utiliser quand |
|---|---|
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 (un téléchargement, une base de données, un blob). fileInfo doit porter la bonne extension — il sélectionne le 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 (HttpPostedFileBase dans MVC; HttpPostedFile dans Web Forms)
using (var ms = new MemoryStream())
{
await file.InputStream.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}Exceptions à gérer :
LicenseException— une licence a été trouvée mais rejetée (le message indique la raison), ou le format nécessite une capacité de plugin que la licence ne concède pas.FormatNotSupportedException— aucun visionneur ne gère l'extension du fichier.InvalidDataException— le contenu est corrompu ou ne correspond pas à son extension.
OpenDocument (synchronous)
Pour le code-behind Web Forms et tout autre code qui n'utilise pas de pages asynchrones :
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)Chacun renvoie le jeton et le stocke également dans viewer.Token. fileName doit porter la bonne extension. Ces wrappers sont sûrs à appeler depuis une page Web Forms : le chemin d'ouverture ne reprend jamais le contexte de requête ASP.NET, ainsi l'attente ne peut pas provoquer de blocage. Ce n'est pas vrai pour chaque API asynchrone Doconut — voir la section Web Forms de Plugin de Convertisseur.
CloseDocument (Fermer le document)
void CloseDocument(string token)Supprime la session (libérant immédiatement le moteur de document), supprime l'octroi du jeton de la session ASP.NET de la requête en cours, et révoque le jeton. Optionnel — l'expiration glissante effectue le même nettoyage — mais recommandé pour les gros documents.
Session queries (Requêtes de session)
| Membre | Retourne |
|---|---|
int GetPageCount(string token) | Nombre total de pages du document ouvert |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | Taille de page rendue par défaut à 100 % de zoom — l'espace de coordonnées pour les annotations intégré dans le code |
IReadOnlyList<string> GetWorksheetNames(string token) | Feuilles de calcul rendues, dans l'ordre du classeur ; vide pour les autres documents |
Chaque appel lève InvalidOperationException (Document session not found. Please re-open document.) si le jeton est inconnu ou expiré, et ArgumentException pour un jeton vide.
DocOptions (Options du 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). |
string | Watermark | "" | Texte de filigrane personnalisé dessiné sur les pages rendues — voir ci‑dessous. |
int | TimeOut | 60 | Expiration glissante de la session, en minutes. |
string | BrowserId | "" | Fermes Web : le navigateur auquel le ticket signé est lié. Définissez‑le avec DoconutFarmBinding.EnsureBrowserId (voir Sessions et sécurité). |
string | UserId | "" | Fermes Web : l'utilisateur connecté auquel le ticket est lié, provenant de DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | Obsolète. Définissez ImageResolution dans la configuration du format à la place. |
bool | IsSecured | true | Réservé ; non appliqué. Le contrôle d'accès est DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | Conservé pour le code migré depuis le package classique. Ils n'activent pas le mode ferme — AddDoconutDistributed le fait. |
bool | EditMode | false | Réservé pour l'éditeur distribué séparément ; laissez false. |
Custom watermark (Filigrane personnalisé)
DocOptions.Watermark prend six champs séparés par des tildes. Un ^ optionnel en tête demande la disposition « 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 ^ | ^ | Disposition « tous les coins » optionnelle. Sans elle, le placement normal est utilisé. |
| Texte | Confidential | Texte dessiné sur chaque page. Il ne doit pas être vide. |
| Couleur | Red | Une couleur nommée. |
| TaillePolice | 24 | Taille de police ; une entrée numérique invalide revient à la valeur par défaut. |
| NomPolice | Verdana | Famille de police. Elle doit être installée sur le serveur — Windows Server possède moins de polices qu'un poste de travail. |
| Opacité | 80 | 0 à 255. Elle doit être analysable. |
| Angle | -45 | 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 un texte Invalid Watermark visible au lieu de disparaître silencieusement.
License decision (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é |
| Licence temporaire/démo active | Non | Page propre |
| Licence temporaire/démo active | Oui | Filigrane personnalisé |
| Licence manquante, rejetée, expirée, de mauvaise version ou de domaine invalide | L'une ou l'autre | Filigrane d'évaluation ; la valeur personnalisée ne le remplace pas |
La même décision s'applique aux pages servies et aux exportations d'annotations. Un filigrane personnalisé est une fonctionnalité d'une application sous licence, et non un moyen de remplacer le filigrane d'évaluation.
API d'annotations
Chargement et export d'annotations côté serveur. Le guide complet se trouve dans Annotations.
| 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 des 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 l'enveloppe encodée 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 |
Métadonnées DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Dans ce package, il renvoie toujours null, et la requête de métadonnées du widget répond 501 Not Implemented : la lecture des balises DICOM n'est pas disponible sur .NET Framework. Le rendu DICOM — pages, images, et animation — fonctionne. Voir Plugin DICOM.
Assistants de ressources — ReferenceCss / ReferenceScripts
Émettre les balises <link> et <script> pour les ressources que le module de ressources fournit sous DoconutOptions.ResourcesPath, dans l'ordre de dépendance. Les fichiers des fonctionnalités soumises à licence (Recherche, Annotation) sont émis uniquement lorsque la licence les autorise.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // état de la licence, pour protéger le code d'initialisation du ruban
bool IsAnnotationEnabled { get; }CssConfig drapeaux : IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (lié à la recherche), IncludeAnnotationCss (lié à l'annotation).
ScriptConfig drapeaux : IncludeJQuery (requis par tous les autres), IncludeBootstrap, IncludeViewerScripts (les scripts principaux du visualiseur), IncludeSearchScripts et IncludeSearchBar (lié à la recherche), IncludeAnnotationScripts et IncludeAnnotationBar (lié à l'annotation), EmitFeatureFlags (par défaut true : écrit également un script window.Doconut.features = { search, annotation, editor } en ligne ; réglez-le sur false sous une Content-Security-Policy qui bloque les scripts en ligne).
Les deux renvoient du HTML : générez-les avec @Html.Raw(...) dans MVC 5 (produisez-les dans le contrôleur — les vues n'ont pas de @inject) ou avec <%= %> dans Web Forms. Démarrage rapide montre les deux.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)Renvoie un bloc <script> qui initialise le widget sur l'élément d'identifiant elementId et affiche le document : docViewer({...}) construit à partir du ViewerConfig (par défaut : BasePath: '/', ResPath: 'doconut-res/images'), puis .View(token). Placez-le après les scripts du visualiseur. Le script généré ne conserve aucune référence à l'objet du visualiseur, ainsi une page avec sa propre barre d'outils doit initialiser le widget manuellement. Voir ViewerConfig.
Ferme Web
string? AccessToken contient le ticket signé émis par la dernière ouverture lorsque le mode distribué est actif et que UnsafeMode est false ; il est null sur un serveur unique. Envoyez-le au widget avec le jeton : objViewer.View(token, accessToken).
Cette page était-elle utile ?