Dépannage

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

Le visualiseur n’affiche rien

Zone du visualiseur 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.

HTTP 500 avec :

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

La sécurité par jeton 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 middleware Doconut. L’état de session nécessite également un cache : dans une application minimal‑API ajoutez builder.Services.AddDistributedMemoryCache(), sinon l’application s’arrête au démarrage avec Unable to resolve service for type 'IDistributedCache' (les applications MVC et Razor Pages enregistrent déjà un cache).

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

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 page (configuration cross‑origin, politique SameSite, client API sans jarre de cookies), ou l’application a redémarré (nouvelles clés de session). Il s’agit du niveau de sécurité qui fonctionne comme prévu — voir Concepts de base → Sessions et sécurité.

Une image d’erreur indiquant :

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. Ré‑ouvrez le document pour obtenir un nouveau jeton.

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

Ce sont les modes d’échec à suspecter en premier lorsqu’une application est migrée. Les trois cas laissent le serveur parfaitement fonctionnel, rendent le document correctement et ne signalent rien dans la console du navigateur.

Un indicateur d’activité 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 semblables. Le visualiseur précédent recherchait ces noms ; celui‑ci ne le fait pas. Le gestionnaire qui aurait caché l’indicateur ne s’exécute jamais. Passez les fonctions en tant qu’options :

objctlDoc = $('#div_ctlDoc').docViewer({
    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 ConfigurationDuVisionneur.

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

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 Déploiements distribués.

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 de build hors de la fenêtre de version/mise à jour de la licence). Cet état bloque l’ouverture (échec immédiat) plutôt que de passer à un filigrane ; lisez License.RejectionMessage pour connaître la raison.

LicenseException :

This document type requires the 'Dicom' plugin license.

L’extension n’est prise en charge que par un plugin (ici : DICOM) et la capacité n’est plus accordée. Enregistrez le plugin et vérifiez lic.IsCapabilityGranted(LicenseCapability.Dicom). Une attribution manquante ou insuffisante, non temporaire, échoue normalement plus tôt lors de AddDoconut().

FormatNotSupportedException :

Document format '<extension>' is not supported.

Aucun visualiseur — intégré, plugin ou personnalisé — ne reconnaît cette extension. Consultez 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 :

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

Vous avez résolu DocumentConverter sans enregistrer le plugin du convertisseur.

Échec du démarrage

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

ArgumentException provenant de AddDoconut():

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 rapide des options — corrigez le chemin incriminé.

Erreurs de compilation / dépendances

Le package ne s'installera pas du tout — Doconut.NETStandard 26.8.0 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 package Doconut.NETFramework à la place.

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

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 à une version inférieure à la dépendance 9.0.x déclarée par Doconut.NETStandard. Supprimez le rétrogradage et laissez NuGet restaurer le graphe de packages (System.Text.Json 9.0.0 et System.Text.Encodings.Web 9.0.0 dans le package 26.8.0 audité).

Un mur d'erreurs de compilation immédiatement après la mise à jour du package — 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 proviennent des lignes using qui ont été déplacées vers l'espace de noms racine Doconut ; suivez le guide Migrer vers .NET Standard 2.1 plutôt que de les corriger une par une.

TypeInitializationException sur le premier fichier de présentation :

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 package). Ne supprimez pas et ne remplacez pas cette dépendance — toute ouverture de PPT/PPTX/PPS/POT/ODP échoue sans elle.

Le rendu est incorrect

Les pages affichent un filigrane — l'application est en mode évaluation : aucun fichier de licence trouvé, une fenêtre temporaire ou d'abonnement expirée, ou un domaine invalide. Inspectez IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la référence IDoconutLicenseService de la page Licensing montre un point de terminaison prêt à l'emploi.

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

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Polices incorrectes ou substituées sous Linux/Docker — le conteneur ne possède pas les polices du document. Dirigez FontFolders (dans WordConfig/PptConfig) vers un répertoire de polices monté.

Les présentations s'ouvrent mais ne s'affichent pas sous Linux/macOS — le rendu actuel de PPT/PPTX/PPS/POT/ODP nécessite le natif libgdiplus ainsi que System.Drawing.EnableUnixSupport=true. Le package fournit System.Drawing.Common 6.0.0 car c'est la dernière version qui prend en charge cet interrupteur.

Fonctionnalité fonctionnant en évaluation, silencieuse en production

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

La recherche ne trouve rien (ou très peu)

• Pour un PDF direct, AllowSearch n'était pas activé lors de l'ouverture. Word, Excel et PowerPoint exposent le même commutateur via leur PdfConfig imbriqué.
• Le contenu est scanné/uniquement image, donc la recherche normale n'a aucune couche de texte à 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 soient rendus via une projection PDF avec une couche de texte native. Word, Excel, PowerPoint, TXT, Visio, email, EPUB et MHT sont recherchables avec leurs paramètres de catalogue par défaut.
• objViewer.CanSearch() renvoie 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.

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.