Débogage des composants du pilote d’imprimante
Si vous développez un plug-in de rendu de pilote d’imprimante ou un plug-in d’interface utilisateur, vous pouvez activer les messages de débogage dans ces composants. Comme expliqué dans la section Variable de débogage global, vous pouvez utiliser une variable de débogage globale pour contrôler le niveau de détail des messages qui apparaissent dans la fenêtre du débogueur.
Vous pouvez utiliser les macros décrites dans la section Déboguer les macros de message pour envoyer des messages à la fenêtre du débogueur dans différentes conditions. En outre, vous pouvez utiliser les informations de cette section pour activer le débogage des messages dans les convertisseurs Microsoft Universal Printer Driver (Unidrv) ou PostScript Printer Driver (Pscript), à condition d’avoir vérifié les builds de ces DLL.
Notes
Les builds vérifiées étaient disponibles sur les versions antérieures de Windows, avant Windows 10 version 1803. Utilisez des outils tels que Driver Verifier et GFlags pour case activée code de pilote dans les versions ultérieures de Windows.
Les étapes de débogage d’un pilote en mode utilisateur et quelques conseils généraux de débogage sont inclus dans les deux sections suivantes.
Préparation du débogage User-Mode
Pour commencer à déboguer les pilotes d’imprimante et leurs composants :
Installez les derniers outils de débogage. Consultez Télécharger les outils de débogage pour Windows
Installer les symboles appropriés à partir de packages de symboles Windows
Notes
Il est très important que vous utilisiez la dernière version du débogueur.
Il est conseillé d’installer la build vérifiée des seuls composants qui vous intéressent pour le débogage. En règle générale, vous remplacez les fichiers binaires de vente au détail suivants par leurs builds vérifiées correspondantes :
Unidrv.dll
Unidrvui.dll
Unires.dll
Vous devez également installer la build vérifiée de l’exemple Oemuni ou du pilote d’imprimante que vous déboguez. L’avantage de l’utilisation de cette approche, par opposition à l’installation d’un système de build vérifié entier, est que vous ne ralentirez pas l’ensemble du système.
Démarrage d’une session de débogage User-Mode
Pour commencer le débogage en mode utilisateur, dans le menu Fichier du débogueur Windbg, sélectionnez Attacher à un processus. Le processus auquel vous attachez le débogueur dépend du scénario que vous tentez de déboguer. Pour les pilotes d’imprimante, vous devez attacher le débogueur à l’application d’impression ou au processus de spouleur (Spoolsv.exe). Gardez à l’esprit que l’application d’impression charge le module de configuration/interface utilisateur, tandis que le processus de spouleur charge le module de rendu. Toutefois, il existe des différences pour l’impression « FILE: », où le spoulage n’a pas lieu et, par conséquent, le module de rendu est également chargé par l’application d’impression. Vous devez donc vous assurer de vous attacher au processus correct.
Notes
Vous n’avez pas besoin de deux ordinateurs distincts pour le débogage en mode utilisateur.
La procédure suivante vous prépare à déboguer l’exemple Oemuni.
Installez l’exemple Oemuni sur le port « FILE: ».
Lancez l’application WordPad en cliquant sur le menu Démarrer , en sélectionnant Tous les programmes, accessoires, puis WordPad.
Dans le menu Fichier WinDbg, sélectionnez Attacher à un processus. Dans la liste des processus disponibles, sélectionnez WordPad.exe.
Démarrez un travail d’impression à partir de WordPad. Vous êtes maintenant prêt à déboguer l’exemple Oemuni.
Vous pouvez activer le débogage détaillé en activant la variable giDebugLevel. Sa valeur par défaut est 3, ce qui indique WARNING. Si la valeur est 1, elle désigne VERBOSE. Pour définir cette dernière valeur avec Unidrv.dll, tapez la commande suivante dans le débogueur :
> ed unidrv!giDebugLevel 1
Lorsque vous exécutez l’exemple Oemuni, la même variable de débogage s’applique également. Pour activer le débogage détaillé, tapez la commande suivante :
> ed oemuni!giDebugLevel 1
Vous pouvez également ajouter vos propres instructions de débogage à l’exemple Oemuni.
Pour plus d’informations sur la définition des valeurs de débogage, consultez la documentation WinDbg, qui décrit les commandes disponibles et décrit les étapes requises pour configurer le débogage en mode utilisateur. Pour accéder à la documentation, dans le menu Aide de WinDbg, sélectionnez Contenu.
Variable de débogage globale
La variable globale giDebugLevel est déclarée par les exemples Oemui et Oemuni dans leurs fichiers Debug.h et Debug.cpp. La valeur de giDebugLevel peut être modifiée par :
- Modification de sa valeur dans le débogueur
- Redéfinition de sa valeur dans le plug-in
Vous pouvez définir giDebugLevel sur l’une des valeurs suivantes :
#define DBG_VERBOSE 1
#define DBG_TERSE 2
#define DBG_WARNING 3
#define DBG_ERROR 4
#define DBG_RIP 5
Macros de message de débogage
Les macros suivantes sont utilisées à des fins de débogage. Plusieurs d’entre eux n’agissent que si la variable globale giDebugLevel, qui contrôle les messages de débogage émis, est définie sur une valeur spécifique. Les macros se développent en espaces blancs sur une build libre. Voici de brèves descriptions de ce qu’ils font et de leurs paramètres.
ASSERT(cond)
- Vérifie si l’expression booléenne dans cond a la valeur TRUE. Si ce n’est pas le cas, la macro force un point d’arrêt.
ASSERTMSG(cond, (msg))
- Vérifie si l’expression booléenne dans cond a la valeur TRUE. Si ce n’est pas le cas, la macro affiche le message en msg et force un point d’arrêt.
ERR((msg))
Affiche le message en msg si le niveau de débogage actuel est <= DBG_ERROR. Le format de message est le suivant :
ERR filename (linenumber): msg
RIP((msg))
- Affiche le message dans msg et force un point d’arrêt.
TERSE((msg))
- Affiche le message en msg si le niveau de débogage actuel est <= DBG_TERSE.
VERBOSE((msg))
- Affiche le message en msg si le niveau de débogage actuel est <= DBG_VERBOSE.
WARNING((msg))
Affiche le message en msg si le niveau de débogage actuel est <= DBG_WARNING. Le format de message est le suivant :
WRN filename (linenumber): msg
Notez que toutes les macros avec un argument msg nécessitent une paire supplémentaire de parenthèses entourant cet argument. Voici deux exemples qui illustrent cette exigence :
ASSERTMSG(x > 0, ("x is less than 0\n"));
WARNING( ("App passed NULL pointer, ignoring...\n") );
Les macros qui contiennent un argument msg sont définies par les exemples Oemui et Oemuni dans leurs en-têtes Debug.h.