Dépannage

Diagnostiquer les erreurs courantes

Chaque message ci‑dessous est le texte littéral produit par Doconut, organisé par symptôme. Trouvez votre erreur, appliquez la correction.

Le visualiseur n'affiche rien

Zone de visualisation vide, console du navigateur remplie de 404 pour /doconut-res/...
UseDoconutResources() est manquant, ou placé après UseDoconut(). Il doit être le premier dans le pipeline.

Le visualiseur signale The viewer handler could not be reached (no response).
La requête n’a jamais reçu de réponse. Une cause fréquente est un BasePath qui commence par / : '/doconut' devient //doconut/DocImage.axd, une requête vers un autre hôte. Écrivez‑le sans la barre oblique initiale (BasePath: 'doconut').

Le visualiseur signale Please make sure your middleware is configured.
Le point de terminaison de la page a répondu 404 : UseDoconut() n’est pas monté à l’endroit où le BasePath du client pointe. Avec app.Map("/doconut", branch => branch.UseDoconut()), le client utilise BasePath: 'doconut'.

HTTP 500 avec :

text
Session middleware not configured. Call UseSession() before UseDoconut().

La sécurité des jetons de Doconut (activée par défaut) nécessite l’état de session ASP.NET. Ajoutez builder.Services.AddSession() et app.UseSession() avant la branche du middleware Doconut. L’état de session nécessite également un cache : dans une application minimal‑API, ajoutez builder.Services.AddDistributedMemoryCache(), ou l’application s’arrête au démarrage avec Unable to resolve service for type 'IDistributedCache' (les applications MVC et Razor Pages en enregistrent déjà un).

Une image d’erreur dans la zone de la page affichant :

text
You Are Not Authorized To View This Page.

Le jeton a été ouvert par une session de navigateur différente. Causes typiques : le cookie de session n’atteint pas les requêtes de la page (configuration cross‑origin, politique SameSite, un client API sans stockage de cookies), ou l’application a redémarré (nouvelles clés de session). Il s’agit de la couche de sécurité qui fonctionne comme prévu — voir Concepts de base → Sessions et sécurité. Le refus est une image servie avec le statut 200, de sorte qu’un moniteur ne vérifiant que les codes d’état la compte comme une page.

Une image d’erreur affichant :

text
Document session not found. Please re-open document.

Le jeton a expiré (fenêtre glissante, 60 minutes par défaut — DocOptions.TimeOut) ou la session a été fermée. Rouvrez le document pour obtenir un nouveau jeton.

Le serveur fonctionne mais la page se comporte mal — sans aucune erreur

Voici les modes de défaillance à suspecter en premier après la migration d’une application. Les trois laissent le serveur en parfait état de marche, affichent correctement le document et ne signalent rien dans la console du navigateur.

Un indicateur de chargement qui ne s’arrête jamais. Vos rappels du visualiseur sont déclarés comme fonctions globales nommées d’après l’identifiant du conteneur — ctlDoc_OnViewerReady() et ses amis. Le visualiseur précédent recherchait ces noms ; celui‑ci ne le fait pas. Le gestionnaire qui aurait masqué l’indicateur ne s’exécute jamais. Passez les fonctions en tant qu’options à la place :

javascript
function ctlDoc_OnViewerBusy() { /* affichez votre indicateur d'activité */ }
function ctlDoc_OnViewerReady() { /* masquez-le */ }
function ctlDoc_Copy(text) { /* utilisez le texte copié */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* signalez la progression */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... vos options existantes ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Le document derrière l’indicateur est correct. La liste complète des options se trouve dans ViewerConfig.

Icônes ou chrome du visualiseur manquants, pages sinon correctes. ResPath est vide ou pointe vers la racine de l’application — correct dans la bibliothèque précédente, incorrect ici. Il doit indiquer le préfixe que UseDoconutResources() monte :

javascript
ResPath: 'doconut-res/images'   // ou '<your ResourcesPath>/images'

Tuiles cassées pour les pages ultérieures lorsqu’on sert depuis un stockage partagé. Les pages encore en cours d’écriture répondent 202 Accepted. Un client sans retryOn409: true considère cela comme une image échouée. Voir Distributed Deployments.

L'ouverture d'un document échoue

LicenseException avec un message de rejet — le fichier de licence a été trouvé mais rejeté (signature invalide, altéré, sur liste noire, ou une version hors de la fenêtre de version/mise à jour de la licence). Cet état empêche l'ouverture (échec rapide) plutôt que de la dégrader en filigrane ; lisez License.RejectionMessage pour la raison.

LicenseException :

text
This document type requires the 'Dicom' plugin license.

L'extension n'est gérée que par un plugin (ici : DICOM). Le plugin est enregistré, mais aucune licence ne lui accorde cette capacité désormais — généralement une licence Temporaire qui a expiré après le démarrage de l'application. Installez une licence qui la délivre et vérifiez IsCapabilityGranted(LicenseCapability.Dicom) sur IDoconutLicenseService. Un droit non temporaire manquant ou insuffisant échoue normalement plus tôt, pendant AddDoconut().

FormatNotSupportedException :

text
Document format '<extension>' is not supported.

Aucun visualiseur — intégré, plugin ou personnalisé — ne revendique cette extension. Vérifiez la liste des formats pris en charge ; pour vos propres formats, DoconutOptions.RegisterViewer peut en ajouter un.

InvalidDataException — le contenu du fichier est corrompu ou ne correspond pas à son extension (par ex. un fichier renommé). Validez les téléchargements avant l'ouverture.

InvalidOperationException :

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Vous avez résolu DocumentConverter sans enregistrer le plugin Convertisseur.

Le démarrage échoue

InvalidOperationException mentionnant un plugin enregistré via AddPlugin — la licence non temporaire actuelle n'accorde pas cette capacité au plugin. Supprimez l'enregistrement ou installez une licence qui le fait. Une licence manquante et un fichier legacy TRIAL n'accordent aucune capacité de plugin.

ArgumentException de AddDoconut() :

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Validation des options d'échec rapide — corrigez le chemin fautif.

Erreurs de construction / dépendances

Le paquet ne s'installera pas du tout — Doconut.NETStandard cible netstandard2.1, donc NuGet refuse un projet .NET Framework. Ce n'est pas une erreur de restauration résolvable : .NET Framework ne peut pas consommer netstandard2.1. Utilisez le paquet Doconut.NETFramework à la place.

Erreur du compilateur CS1705, ou à l'exécution lors de l'ouverture d'un document :

text
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

Votre projet a fixé System.Text.Json ou System.Text.Encodings.Web en dessous de la version 9.0.x des dépendances déclarées par Doconut.NETStandard. Supprimez le rétrogradage et laissez NuGet restaurer le graphe des paquets (System.Text.Json 9.0.0 et System.Text.Encodings.Web 9.0.0 comme déclaré par le paquet).

Un mur d'erreurs de compilation immédiatement après la mise à jour du paquet — c'est attendu. 26.8.0 possède une surface d'API différente de 26.7.0, ce n'est pas une mise à jour compatible. La plupart des erreurs sont les lignes using qui ont été déplacées vers l'espace de noms racine Doconut ; parcourez Migrer vers .NET Standard 2.1 plutôt que de les corriger une par une.

TypeInitializationException sur le premier fichier de présentation :

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

Le moteur de présentation exige strictement System.Drawing.Common 6.0.0 (déclaré par le paquet). Ne supprimez pas ou ne remplacez pas cette dépendance — toute ouverture de PPT/PPTX/PPS/POT/ODP échoue sans elle.

La sortie semble incorrecte

Les pages portent un filigrane — l'application est en mode d'évaluation : aucun fichier de licence trouvé, une licence Temporaire expirée, ou un domaine invalide. Sous une licence Temporaire active, seule la sortie du plugin est filigranée. Une version publiée après la date d'abonnement d'une licence payante n'est pas filigranée : l'ouverture génère LicenseException. Inspectez IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la référence IDoconutLicenseService de la page Licensing montre un point d'accès prêt à l'emploi.

Les documents legacy affichent du texte illisible — les encodages de page de code ne sont pas chargés par défaut. Ajoutez-les une fois au démarrage :

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Polices incorrectes ou substituées — le serveur ne possède pas les polices du document. Installez-les, ou pointez FontFolders (sur WordConfig/PptConfig) vers un dossier qui les contient.

Une annotation d'image apparaît dans le visualiseur mais l'exportation affiche une boîte « Image bloquée » — l'hôte de l'image possède une adresse privée ou de bouclage, que le serveur refuse de récupérer. Voir Annotations.

Fonctionnalité fonctionnée en évaluation, silencieuse en production

La surprise classique du passage en production : une licence Temporaire active accorde toutes les capacités ; votre licence achetée ne donne que ce que vous avez acheté. Les ensembles de recherche et d'annotation peuvent disparaître lorsque leurs capacités sont absentes. Un Convertisseur enregistré ou des plugins DICOM avec une licence non‑temporaire insuffisante échouent pendant AddDoconut(). Comparez IsCapabilityGranted(...) à chaque fonctionnalité que vous activez avant le déploiement.

La recherche ne trouve rien (ou trop peu)

  • Pour un PDF direct, AllowSearch n'était pas activé au moment de l'ouverture. Word, Excel et PowerPoint exposent le même commutateur via leurs PdfConfig imbriqués.
  • Le contenu est scanné/uniquement image, donc la Recherche normale n'a aucune couche de texte à faire correspondre. Utilisez une source contenant du texte ou une projection PDF qui préserve le texte.
  • HTML et MS Project (MPP) ne sont pas recherchables par défaut — définissez DefaultRender = false afin qu'ils se rendent via une projection PDF avec une couche de texte native. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB et MHT sont recherchables avec leurs paramètres de catalogue par défaut.
  • objViewer.CanSearch() est false après l'initialisation — le format résolu n'a aucun chemin de recherche standard. Ce verdict est distinct de la licence de Recherche ; vérifiez les deux.
  • La page lit la valeur de retour de objViewer.Search(...) — le compte arrive dans son troisième argument, un rappel.

Toujours bloqué ?

Isolez le problème avec l'application Quick Start minimale ; s'il se reproduit là, contactez le support avec le document, votre Program.cs, et la sortie des diagnostics de licence.

Cette page était-elle utile ?