Personnalisation de la sortie du débogueur à l’aide de DML

Le langage de balisage du débogueur (DML) fournit un mécanisme permettant d’améliorer la sortie du débogueur et des extensions. À l’instar du code HTML, la prise en charge du balisage du débogueur permet à la sortie d’inclure des directives d’affichage et des informations de non-affichage supplémentaires sous la forme de balises. Les interfaces utilisateur du débogueur, telles que WinDbg, analysent les informations supplémentaires fournies dans DML pour améliorer l’affichage des informations et fournir de nouveaux comportements, tels que l’affichage de grille et le tri. Cette rubrique explique comment personnaliser votre sortie de débogage à l’aide de DML. Pour plus d’informations générales sur l’activation et l’utilisation de DML dans les débogueurs, consultez Utilisation du langage de balisage du débogueur.

DML est disponible dans Windows 10 et versions ultérieures.

Vue d’ensemble de DML

Sur les principaux avantages de DML, il fournit la possibilité de créer un lien vers des informations connexes dans la sortie du débogueur. L’une des balises DML principales est la <balise de lien> qui permet à un producteur de sortie d’indiquer que les informations relatives à une sortie sont accessibles via l’action indiquée du lien. Comme pour les liens HTML dans un navigateur web, cela permet à l’utilisateur de naviguer dans les informations relatives aux liens hypertexte.

L’un des avantages de la fourniture de contenu hypertexte est qu’il peut être utilisé pour améliorer la détectabilité des fonctionnalités d’extension du débogueur et du débogueur. Le débogueur et ses extensions contiennent une grande quantité de fonctionnalités, mais il peut être difficile de déterminer la commande appropriée à utiliser dans différents scénarios. Les utilisateurs doivent simplement savoir quelles commandes peuvent être utilisées dans des scénarios spécifiques. Les différences entre le débogage utilisateur et le débogage du noyau ajoutent une complexité supplémentaire. Cela signifie souvent que de nombreux utilisateurs ignorent les commandes de débogage qui pourraient les aider. Les liens DML permettent aux commandes de débogage arbitraires d’être encapsulées dans d’autres présentations, telles que du texte descriptif, des systèmes de menu cliquables ou de l’aide liée. À l’aide de DML, la sortie de commande peut être améliorée pour guider l’utilisateur vers d’autres commandes associées pertinentes pour la tâche en cours.

Prise en charge du débogueur DML

• La fenêtre de commande dans WinDbg prend en charge tout le comportement DML et affiche les couleurs, les styles de police et les liens.
• Les débogueurs de console (ntsd, cdb et kd) prennent uniquement en charge les attributs de couleur de DML, et les seuls en cas d’exécution dans une console réelle avec le mode couleur activé.
• Les débogueurs avec des sessions d’E/S, ntsd-d ou remote.exe redirigées n’affichent aucune couleur.

Spécification de contenu DML

DML n’est pas destiné à être un langage de présentation complet tel que HTML. DML est délibérément très simple et n’a qu’une poignée de balises.

Étant donné que tous les outils de débogueur ne prennent pas en charge le texte enrichi, DML est conçu pour permettre la traduction simple entre DML et texte brut. Cela permet à DML de fonctionner dans tous les outils de débogueur existants. Les effets tels que les couleurs peuvent facilement être pris en charge, car leur suppression ne supprime pas le texte contenant les informations réelles.

DML n’est pas XML. DML ne tente pas de transporter d’informations sémantiques ou structurées. Comme mentionné ci-dessus, il doit y avoir un simple mappage entre DML et texte brut. Pour cette raison, les balises DML sont toutes ignorées.

DML n’est pas extensible ; toutes les balises sont prédéfinies et validées pour fonctionner sur tous les outils de débogueur existants.

Structure de balise

Comme pour XML, les balises DML sont données sous la forme d’un nom de balise de départ <[args]> et d’un /tagname> suivant<.

Caractères spéciaux

Le contenu DML suit approximativement les règles XML/HTML pour les caractères spéciaux. Les caractères &, <et > « sont spéciaux et ne peuvent pas être utilisés en texte brut. Les versions équivalentes en échappement sont &, <, > et ». Par exemple, ce texte :

« Alice & Bob pensent 3 < 4 »

est converti en DML suivant.

"Alice & Bob think 3 &lt 4"

Caractères de mise en forme du langage de programmation C

Un écart significatif par rapport aux règles XML/HTML est que le texte DML peut inclure des caractères de mise en forme de style flux du langage de programmation C, tels que \b, \t, \r et \n. Il s’agit de prendre en charge la compatibilité avec la production et la consommation de texte du débogueur existant.

Exemple DML

Supposons que le fichier C:\Dml_Experiment.txt contienne les lignes suivantes.

My DML Experiment
<link cmd="lmD musb*">List modules that begin with usb.</link>

La commande suivante affiche le texte et le lien dans la fenêtre Explorateur de commandes.

.browse .dml_start c:\Dml_Experiment.txt

Si vous cliquez sur le lien Lister les modules qui commencent par usb , vous voyez une sortie similaire à l’image suivante.

Comportement du clic droit dans DML

Le comportement de clic droit est disponible dans DML. Cet exemple montre comment définir le comportement de clic droit à l’aide <de altlink> pour envoyer une commande de point d’arrêt (Set Breakpoint) et envoyer l’u (Annuler) avec un clic régulier.

<link cmd="u MyProgram!memcpy">
<altlink name="Set Breakpoint (bp)" cmd="bp MyProgram!memcpy" />
u MyProgram!memcpy
</link>

Référence de balise DML

<Lien>

<link [name="text"] [cmd="debugger_command"][alt="Hover text to display"] [section="name"]>link text</link>

La balise de lien est le mécanisme d’hyper-liaison de base dans DML. Il dirige les interfaces utilisateur qui prennent en charge la présentation DML pour afficher le texte du lien sous la forme d’un lien cliquable. Lorsqu’un lien avec une spécification cmd est cliqué, la commande débogueur est exécutée et sa sortie doit remplacer la sortie actuelle.

Les arguments nom et section permettent la navigation entre les liens nommés, comme le nom> html <et #name prise en charge. Lorsqu’un lien avec un argument de section est cliqué sur l’interface utilisateur recherche un lien nommé avec un nom correspondant et le fait défiler dans l’affichage. Cela permet aux liens de pointer vers différentes sections de la même page (ou une section particulière d’une nouvelle page). Le nom de section de DML est distinct pour éviter d’avoir à définir une nouvelle syntaxe qui autoriserait un nom de section à la fin de la chaîne de commande.

La conversion en texte brut supprime les balises.

Exemple

<b> Handy Links </b>
<link cmd="!dml_proc">Display process information with DML rendering.</link>
<link cmd="kM">Display stack information with DML rendering.</link>

Exemple

Cet exemple montre l’utilisation de l’attribut alt pour créer du texte qui s’affichera lorsque vous pointez sur le lien DML.

<b>Hover Example</b>
<link cmd="lmD" alt="This link will run the list modules command and display the output in DML format">LmD</link>

<altlink>

<altlink [name="text"] [cmd="debugger_command"] [section="name"]>alt link text</altlink>

La <balise altlink> fournit un comportement de clic droit est disponible dans DML. Lorsqu’un lien avec une spécification cmd est cliqué, la commande débogueur est exécutée et sa sortie doit remplacer la sortie actuelle. L’onglet <Altlink> est normalement associé à la balise de lien> pour prendre en charge le <comportement de clic droit et régulier.

La conversion en texte brut supprime les balises.

Exemple

Cet exemple montre comment définir le comportement de clic droit à l’aide <de altlink> pour envoyer une commande de point d’arrêt bp (Définir le point d’arrêt) et envoyer l’u (Désassembler) avec un clic régulier.

<link cmd="u MyProgram!memcpy">
<altlink name="Set Breakpoint (bp)" cmd="bp MyProgram!memcpy" />
u MyProgram!memcpy
</link>

<Exec>

<exec cmd="debugger_command">texte< descriptif/exec>

Une balise exec est similaire à une balise de lien dans la mesure où le texte descriptif doit être présenté comme un élément cliquable. Toutefois, lorsque la balise exec est utilisée dans une fenêtre de navigateur de commandes, la commande donnée est exécutée sans remplacer la sortie actuelle, cette balise permet d’exécuter les commandes en un clic, à partir d’un menu.

La conversion en texte brut supprime les balises.

Exemple

Cet exemple montre comment définir deux commandes avec un clic régulier.

<b>Exec Sample</b>
<exec cmd="!dml_proc">Display process information with DML rendering.</exec>
<exec cmd="kM">Display stack information with DML rendering.</exec>

<B>

<b>Texte< en gras/b>

Cette balise demande en gras. Les <propriétés b>, <i> et <u> peuvent être imbriquées pour avoir un mélange des propriétés.

La conversion en texte brut supprime les balises.

Exemple

Cet exemple montre comment mettre en gras du texte.

<b>This is bold Text</b>

<Je>

<i>texte< en italique/i>

Cette balise demande une italique. Les <propriétés b>, <i> et <u> peuvent être imbriquées pour avoir un mélange des propriétés.

La conversion en texte brut supprime les balises.

Exemple

Cet exemple montre comment italiquer du texte.

<i>This is italicized Text</i>

<U>

<u>texte< souligné/u>

Cette balise demande du texte souligné. Les <propriétés b>, <i> et <u> peuvent être imbriquées pour avoir un mélange des propriétés.

La conversion en texte brut supprime les balises.

Exemple

Cet exemple montre comment souligner du texte.

<u>This is underlined Text</u>

Exemple

Cet exemple montre comment combiner des balises en gras, souligner et italiquer du texte.

<b><u><i>This is bold, underlined and italizized text. </i></u></b> 

<col>

<col fg="name » bg="name">text</col>

Demandez des couleurs de premier plan et d’arrière-plan pour le texte. Les couleurs sont données sous la forme de noms de couleurs connues au lieu de valeurs absolues, car cela permet aux clients de contrôler le type de couleur qu’ils voient. Noms de couleurs actuels (les valeurs par défaut s’appliquent uniquement à WinDbg).

Balises d’éléments de premier plan et d’arrière-plan

Étiquettes d’élément unique du code source

Exemple de code DML

Cet exemple de code illustre ce qui suit.

• Appel de commandes de débogage
• Implémentation de commandes de clic droit
• Implémentation du pointage sur le texte
• Utilisation de la couleur et du texte enrichi

<col fg="srckw" bg="wbg"> <b>
*******************************************************
*** Example debug commands for crash dump analysis ****
*******************************************************
</b></col>
<col fg="srcchar" bg="wbg"><i>
**** Hover over commands for additional information ****
        **** Right-click for command help ****
</i></col>

<col fg="srccmnt" bg="wbg"><b>*** Common First Steps for Crash Dump Analysis ***</b> </col>
<link cmd=".symfix" alt="Set standard symbol path using .symfix">.symfix<altlink name="Help about .symfix" cmd=".hh .symfix" /> </link> - Set standard symbol path
<link cmd=".sympath+ C:\Symbols" alt="This link adds additional symbol directories">.sympath+ C:\Symbols<altlink name="Help for .sympath" cmd=".hh .sympath" /> </link> - Add any additional symbol directories, for example C:\Symbols
<link cmd=".reload /f" alt="This link reloads symbols">.reload /f<altlink name="Help for .reload" cmd=".hh .reload" /> </link> - Reloads symbols to make sure they are in good shape
<link cmd="!analyze -v" alt="This link runs !analyze with the verbose option">!analyze -v<altlink name="Help for !analyze" cmd=".hh !analyze" /> </link> - Run !analyze with the verbose option
<link cmd="vertarget" alt="This link runs checks the target version">vertarget<altlink name="Help for vertarget" cmd=".hh vertarget" /></link> - Check the target version
<link cmd="version" alt="This link displays the versions in use">version<altlink name="Help for version" cmd=".hh version" /></link> - Display the versions in use
<link cmd=".chain /D" alt="This link runs .chain">.chain /D<altlink name="Help for .chain" cmd=".hh .chain" /></link> - Use the .chain /D command to list debugger extensions
<link cmd="kM" alt="This link displays the stack backtrace using DML">kD<altlink name="Help for k" cmd=".hh k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)" /> </link> - Display the stack backtrace using DML rendering
<link cmd="lmD" alt="This link will run the list modules command and display the output in DML format">LmD<altlink name="Help for lmD" cmd=".hh lm" /> </link> - List modules command and display the output in DML format
<link cmd=".help /D" alt="Display help for commands">.help /D <altlink name="Help for .dot commands" cmd=".hh commands" /></link> - Display help for commands in WinDbg
<link cmd=".hh" alt="Start help">.hh<altlink name="Debugger Reference Help".hh Contents" cmd=".hh Debugger Reference" /></link> - Start help

<col fg="srccmnt" bg="wbg"><b>*** Registers and Context ***</b></col>
<link cmd="r" alt="This link displays registers">r<altlink name="Help about r command" cmd=".hh r" /></link>  - Display registers
<link cmd="dt nt!_CONTEXT" alt="This link displays information about nt_CONTEXT">dt nt!_CONTEXT<altlink name="Help about the dt command" cmd=".hh dt" /></link> - Display information about nt_CONTEXT
<link cmd="dt nt!_PEB" alt="This link calls the dt command to display nt!_PEB">dt nt!_PEB<altlink name="Help about dt command" cmd=".hh dt" /></link> - Display information about the nt!_PEB
<link cmd="ub" alt="This link unassembles backwards">ub<altlink name="Help about ub command" cmd=".hh u, ub, uu (Unassemble)" /></link> - Unassemble Backwards

<col fg="srcchar" bg="wbg"><i>
**** Note: Not all of the following commands will work with all crash dump data ****
</i></col>
<col fg="srccmnt" bg="wbg"><b>*** Device Drivers ***</b></col>
<link cmd="!devnode 0 1" alt="This link displays the devnodes">!devnode 0 1<altlink name="Help about !devnode command" cmd=".hh !devnode" /></link> - Display devnodes
<link cmd=".load wdfkd.dll;!wdfkd.help" alt="Load wdfkd extensions and display help">.load wdfkd.dll;!wdfkd.help<altlink name="Help about the wdfkd extensions" cmd=".hh !wdfkd" /></link> - Load wdfkd extensions and display help
<link cmd="!wdfkd.wdfldr" alt="This link displays !wdfkd.wdfldr">!wdfkd.wdfldr<altlink name="Help about !wdfkd.wdfldr" cmd=".hh !wdfkd.wdfldr" /></link>  - Display WDF framework driver loader information
<link cmd="!wdfkd.wdfumtriage" alt="This link displays !wdfkd.umtriage">!wdfkd.umtriage<altlink name="Help about !wdfkd.umtriage" cmd=".hh !wdfkd_wdfumtriage" /></link> - Display WDF umtriage driver information

<col fg="srccmnt" bg="wbg"><b>*** IRPs and IRQL ***</b></col>
<link cmd="!processirps" alt="This link displays process IRPs">!processirps<altlink name="Help about !processirps command" cmd=".hh !processirps" /></link> - Display process IRPs
<link cmd="!irql" alt="This link displays !irql">!irql<altlink name="Help about !irql command" cmd=".hh !irql" /></link> - Run !irql

<col fg="srccmnt" bg="wbg"><b>*** Variables and Symbols ***</b></col>
<link cmd="dv" alt="This link calls the dv command">dv<altlink name="Help about dv command" cmd=".hh dv" /></link> - Display the names and values of all local variables in the current scope

<col fg="srccmnt" bg="wbg"><b>*** Threads, Processes, and Stacks ***</b></col>
<link cmd="!threads" alt="This link displays threads">!threads<altlink name="Help about the !threads command" cmd=".hh !threads" /></link> - Display threads
<link cmd="!ready 0xF" alt="This link runs !ready 0xF">!ready 0xF<altlink name="Help about the !ready command" cmd=".hh !ready" /></link> - Display threads in the ready state
<link cmd="!process 0 F" alt="This link runs !process 0 F ">!process 0 F<altlink name="Help about the !process command" cmd=".hh !process" /></link> - Run !process 0 F
<link cmd="!stacks 2" alt="This link displays stack information using !stacks 2 ">!stacks 2<altlink name="Help about the !stacks command" cmd=".hh !stacks" /></link> - Display stack information using !stacks 2
<link cmd=".tlist" alt="This link displays a process list using TList ">tlist<altlink name="Help about the TList command" cmd=".hh .tlist" /></link> - Display a process list using tlist
<link cmd="!process" alt="This link displays process ">!process<altlink name="Help about the !process command" cmd=".hh !process" /></link> - Display process information
<link cmd="!dml_proc" alt="This link displays process information with DML rendering.">!dml_proc<altlink name="Help about the !dml_proc command" cmd=".hh !dml_proc" /></link> - Display process information with DML rendering

Cet exemple de code illustre l’utilisation des balises de couleur et de mise en forme.

*** Text Tag Examples ****

<b>This is bold text</b>
<u>This is underlined text</u>
<i>This is italizized text</i>
<b><u><i>This is bold, underlined and italizized text</i></u></b>

<b>Color Tag Examples</b>
<col fg="wfg" bg="wbg"> This is standard foreground / background text </col>
<col fg="empfg" bg="empbg"> This is emphasis foreground / background text </col>
<col fg="subfg" bg="subbg"> This is subdued foreground / background text </col>
<col fg="clfg" bg="clbg"> Test Text - Current Line</col>

<b>Other Tags Sets</b>
<col fg="normfg" bg="normbg"> Test Text - Normal (normfg / normbg) </col>
<col fg="warnfg" bg="warnbg"> Test Text - Warning (warnfg / warnbg) </col>
<col fg="errfg" bg="errbg"> Test Text - Error (errfg / errbg) </col>
<col fg="verbfg" bg="verbbg"> Test Text - Verbose (verbfg / verbbg) </col>

<b>Changed Text Tag Examples</b>
<col fg="changed" bg="wbg"> Test Text - Changed</col>

<b>Source Tags - using wbg background</b>
<col fg="srcnum" bg="wbg"> Test Text - srcnum  </col>
<col fg="srcchar" bg="wbg"> Test Text - srcchar  </col>
<col fg="srcstr" bg="wbg"> Test Text - srcstr  </col>
<col fg="srcid " bg="wbg"> Test Text - srcid   </col>
<col fg="srckw" bg="wbg"> Test Text - srckw </col>
<col fg="srcpair" bg="empbbg"> Test Text - srcpair </col>
<col fg="srccmnt" bg="wbg"> Test Text - srccmnt  </col>
<col fg="srcdrct" bg="wbg"> Test Text - srcdrct </col>
<col fg="srcspid" bg="wbg"> Test Text - srcspid </col>
<col fg="srcannot" bg="wbg"> Test Text - srcannot </col>

<b>Source Tags - using empbg background</b>
<col fg="srcnum" bg="empbg"> Test Text - srcnum  </col>
<col fg="srcchar" bg="empbg"> Test Text - srcchar  </col>
<col fg="srcstr" bg="empbg"> Test Text - srcstr  </col>
<col fg="srcid " bg="empbg"> Test Text - srcid   </col>
<col fg="srckw" bg="empbg"> Test Text - srckw </col>
<col fg="srcpair" bg="empbbg"> Test Text - srcpair </col>
<col fg="srccmnt" bg="empbg"> Test Text - srccmnt  </col>
<col fg="srcdrct" bg="empbg"> Test Text - srcdrct </col>
<col fg="srcspid" bg="empbg"> Test Text - srcspid </col>
<col fg="srcannot" bg="empbg"> Test Text - srcannot </col>

<b>Source Tags - using subbg background</b>
<col fg="srcnum" bg="subbg"> Test Text - srcnum  </col>
<col fg="srcchar" bg="subbg"> Test Text - srcchar  </col>
<col fg="srcstr" bg="subbg"> Test Text - srcstr  </col>
<col fg="srcid " bg="subbg"> Test Text - srcid   </col>
<col fg="srckw" bg="subbg"> Test Text - srckw </col>
<col fg="srcpair" bg="subbg"> Test Text - srcpair </col>
<col fg="srccmnt" bg="subbg"> Test Text - srccmnt  </col>
<col fg="srcdrct" bg="subbg"> Test Text - srcdrct </col>
<col fg="srcspid" bg="subbg"> Test Text - srcspid </col>
<col fg="srcannot" bg="subbg"> Test Text - srcannot </col>

Ajouts DML à l’interface dbgeng

Les API Debugger Engine et Extension fournissent une interface permettant d’utiliser le moteur de débogueur pour créer des applications personnalisées. Vous pouvez également écrire des extensions personnalisées qui s’exécuteront dans WinDbg, KD, CDB et NTSD. Pour plus d’informations, consultez Écriture d’extensions DbgEng. Cette section décrit les améliorations DML disponibles pour les interfaces du moteur de débogueur.

Le dbgeng dispose déjà d’un ensemble de méthodes d’entrée et d’interfaces de sortie de gestion du texte. L’utilisation de DML ne nécessite que la spécification du type de contenu transporté dans le texte d’entrée et de sortie.

Fourniture de contenu DML à dbgeng

L’indicateur de contrôle de sortie DEBUG_OUTCTL_DML indique que le texte généré par une méthode dbgeng doit être géré en tant que contenu DML. Si cet indicateur n’est pas donné, le texte est traité comme un contexte de texte brut. DEBUG_OUTCTL_DML pouvez être utilisé avec les méthodes suivantes.

• IDebugControl4 ::ControlledOutput
• IDebugControl4 ::ControlledOutputVaList
• IDebugControl4 ::ControlledOutputWide
• IDebugControl4 ::ControlledOutputVaListWide

Le texte donné doit suivre les règles DML pour les caractères valides.

Toutes les routines de sortie ont été améliorées pour autoriser un nouveau spécificateur de format %[h|w]Y{t}. Ce spécificateur de format a un pointeur de chaîne en tant qu’argument et indique que le texte donné est du texte brut et doit être converti au format DML pendant le traitement de la sortie. Cela offre aux appelants un moyen simple d’inclure du texte brut dans le contenu DML sans avoir à effectuer eux-mêmes une pré-conversion au format DML. Les qualificateurs h et w indiquent du texte ANSI ou Unicode, comme avec %s.

Le tableau suivant récapitule l’utilisation du spécificateur de format %Y.

%Y{t} : chaîne entre guillemets. Convertit le texte en DML si le format de sortie (premier argument) est DML.

%Y{T} : chaîne entre guillemets. Convertit toujours le texte en DML, quel que soit le format de sortie.

%Y{s} : chaîne non mise en guillemets. Convertit le texte en DML si le format de sortie (premier argument) est DML.

%Y{S} : chaîne non mise en guillemets. Convertit toujours le texte en DML, quel que soit le format de sortie.

%Y{as} : ULONG64. Ajoute une chaîne vide ou 9 caractères d’espacement pour le remplissage de la partie 32 bits élevée des champs de pointeur mis en forme du débogueur. L’espace supplémentaire génère 9 espaces, ce qui inclut les 8 zéros supérieurs plus le caractère ' .

%Y{ps} : ULONG64. Espace supplémentaire pour le remplissage des champs de pointeur mis en forme du débogueur (inclut les 8 zéros supérieurs plus le caractère ' ).

%Y{l} : ULONG64. Adresse en tant qu’informations de ligne source.

Cet extrait de code illustre l’utilisation du spécificateur de format %Y.

HRESULT CALLBACK testout(_In_ PDEBUG_CLIENT pClient, _In_ PCWSTR /*pwszArgs*/)
{
    HRESULT hr = S_OK;

    ComPtr<IDebugControl4> spControl;
    IfFailedReturn(pClient->QueryInterface(IID_PPV_ARGS(&spControl)));

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{t}: %Y{t}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{T}: %Y{T}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{s}: %Y{s}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{S}: %Y{S}\n", L"Hello <World>");

    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{t}: %Y{t}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{T}: %Y{T}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{s}: %Y{s}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{S}: %Y{S}\n", L"Hello <World>");

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{a}: %Y{a}\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{as} 64bit   : '%Y{as}'\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{as} 32value : '%Y{as}'\n", (ULONG64)0x1);

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{ps} 64bit   : '%Y{ps}'\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{ps} 32value : '%Y{ps}'\n", (ULONG64)0x1);

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{l}: %Y{l}\n", (ULONG64)0x00007ffa7da163c0);

    return hr;

}

Cet exemple de code génère la sortie suivante.

0:004> !testout
DML/NORMAL Y{t}: "Hello <World>"
DML/NORMAL Y{T}: "Hello <World>"
DML/NORMAL Y{s}: Hello <World>
DML/NORMAL Y{S}: Hello <World>
TEXT/NORMAL Y{t}: "Hello <World>"
TEXT/NORMAL Y{T}: "Hello &lt;World&gt;"
TEXT/NORMAL Y{s}: Hello <World>
TEXT/NORMAL Y{S}: Hello &lt;World&gt;
DML/NORMAL Y{a}: 00007ffa`7da163c0
DML/NORMAL Y{as} 64bit   : '         '
DML/NORMAL Y{as} 32value : '         '
DML/NORMAL Y{ps} 64bit   : '        '
DML/NORMAL Y{ps} 32value : '        '
DML/NORMAL Y{l}: [d:\th\minkernel\kernelbase\debug.c @ 443]

Un indicateur de contrôle supplémentaire, DEBUG_OUTCTL_AMBIENT_DML, permet la spécification du texte contextuel DML sans modifier les attributs de contrôle de sortie. DEBUG_OUTCTL_AMBIENT_TEXT a également été ajouté en tant qu’alias plus descriptif pour le DEBUG_OUTCTL_AMBIENT existant précédemment. Les indicateurs de contrôle de sortie sont définis dans dbgeng.h.

#define DEBUG_OUTCTL_DML               0x00000020

// Special values which mean leave the output settings
// unchanged.
#define DEBUG_OUTCTL_AMBIENT_DML       0xfffffffe
#define DEBUG_OUTCTL_AMBIENT_TEXT      0xffffffff

// Old ambient flag which maps to text.
#define DEBUG_OUTCTL_AMBIENT           DEBUG_OUTCTL_AMBIENT_TEXT

Fourniture de contenu DML à partir d’un débogué

Le dbgeng a été amélioré pour analyser la sortie de débogage pour un marqueur spécial, qui indique que le texte restant dans une partie de sortie de débogage doit être traité comme DML. Le changement de mode s’applique uniquement à une seule partie de la sortie déboguée, telle qu’une seule chaîne OutputDebugString, et n’est pas un commutateur de mode global.

Cet exemple montre une combinaison de sortie simple et DML.

OutputDebugString(“This is plain text\n<?dml?>This is <col fg=\”emphfg\”>DML</col> text\n”);

La sortie produite aura une ligne de texte brut suivie d’une ligne de DML où l’acronyme DML est affiché dans une couleur différente.

IDebugOutputCallbacks2

IDebugOutputCallbacks2 permet aux clients d’interface dbgeng de recevoir du contenu DML complet pour la présentation. IDebugOutputCallbacks2 est une extension de IDebugOutputCallbacks (et non IDebugOutputCallbacksWide) afin qu’elle puisse être transmise à la méthode SetOutputCallbacks existante. Le moteur effectue une requête QueryInterface pour IDebugOutputCallbacks2 pour voir quelle interface l’objet de rappel de sortie entrant prend en charge. Si l’objet prend en charge IDebugOutputCallbacks2, toute la sortie est envoyée via les méthodes étendues IDebugOutputCallbacks2 ; La méthode IDebugOutputCallbacks ::Output de base ne sera pas utilisée.

Les nouvelles méthodes sont les suivantes :

• IDebugOutputCallbacks2 ::GetInterestMask : permet à l’objet de rappel de décrire les types de notifications de sortie qu’il souhaite recevoir. Le choix de base est entre le contenu en texte brut (DEBUG_OUTCBI_TEXT) et le contenu DML (DEBUG_OUTCBI_DML). En outre, l’objet de rappel peut également demander la notification de vidages explicites (DEBUG_OUTCBI_EXPLICIT_FLUSH).

• IDebugOutputCallbacks2 ::Output2 : toutes les notifications IDebugOutputCallbacks2 passent par Output2. Le paramètre Which indique le type de notification entrant alors que les paramètres Flags, Arg et Text portent la charge utile de notification. Les notifications sont les suivantes :

  • DEBUG_OUTCB_TEXT : sortie en texte brut. Les indicateurs proviennent de DEBUG_OUTCBF_*, Arg est le masque de sortie et Text est le texte brut. Cela ne sera reçu que si DEBUG_OUTCBI_TEXT a été donné dans le masque d’intérêt.

  • DEBUG_OUTCB_DML : sortie de contenu DML. Les indicateurs proviennent de DEBUG_OUTCBF_*, Arg est le masque de sortie et Text est le contenu DML. Cela ne sera reçu que si DEBUG_OUTCBI_DML a été donné dans le masque d’intérêt.

  • DEBUG_OUTCB_EXPLICIT_FLUSH : un appelant a appelé FlushCallbacks sans texte mis en mémoire tampon. Normalement, lorsque le texte mis en mémoire tampon est vidé, l’indicateur DEBUG_OUTCBF_COMBINED_EXPLICIT_FLUSH est défini, en pliant les deux notifications en une seule. Si aucun texte n’est mis en mémoire tampon, une notification de vidage uniquement est envoyée.

Les indicateurs de masque d’intérêt sont définis dans dbgeng.h, comme indiqué ici.

// IDebugOutputCallbacks2 interest mask flags.
//
// Indicates that the callback wants notifications
// of all explicit flushes.
#define DEBUG_OUTCBI_EXPLICIT_FLUSH 0x00000001
// Indicates that the callback wants
// content in text form.
#define DEBUG_OUTCBI_TEXT           0x00000002
// Indicates that the callback wants
// content in markup form.
#define DEBUG_OUTCBI_DML            0x00000004

#define DEBUG_OUTCBI_ANY_FORMAT     0x00000006

Notez qu’un objet de sortie peut s’inscrire pour du texte et du contenu DML s’il peut les gérer. Pendant le traitement de la sortie du rappel, le moteur choisit le format qui réduit les conversions, la prise en charge des deux peut donc réduire les conversions dans le moteur. Toutefois, cela n’est pas nécessaire et la prise en charge d’un seul format est le mode de fonctionnement attendu.

Conversions automatiques

Le dbgeng est automatiquement converti en texte brut et DML si nécessaire. Par exemple, si un appelant envoie du contenu DML au moteur, le moteur le convertit en texte brut pour tous les clients de sortie qui acceptent uniquement le texte brut. Le moteur convertit également le texte brut en DML pour tous les rappels de sortie qui n’acceptent que DML.

Voir aussi

Utilisation du langage de balisage du débogueur