Anpassen der Debuggerausgabe mithilfe von DML

Die Debugger-Markupsprache (Debugger Markup Language, DML) bietet einen Mechanismus zum Verbessern der Ausgabe des Debuggers und der Erweiterungen. Ähnlich wie HTML ermöglicht die Markupunterstützung des Debuggers, dass die Ausgabe Anzeigedirektiven und zusätzliche Nichtanzeigeinformationen in Form von Tags einschließen kann. Die Debugger-Benutzeroberflächen, z. B. WinDbg, analysieren die in DML bereitgestellten zusätzlichen Informationen, um die Anzeige von Informationen zu verbessern und neue Verhaltensweisen wie Rasteranzeigen und Sortierung bereitzustellen. In diesem Thema wird beschrieben, wie Sie Ihre Debugausgabe mithilfe von DML anpassen können. Allgemeine Informationen zum Aktivieren und Verwenden von DML in den Debuggern finden Sie unter Verwenden der Debuggermarkierungssprache.

DML ist in Windows 10 und höher verfügbar.

DML-Übersicht

Zu den wichtigsten Vorteilen von DML ist es, die Möglichkeit zu bieten, verwandte Informationen in der Debuggerausgabe zu verknüpfen. Eines der primären DML-Tags ist das <Linktag> , mit dem ein Ausgabeproduzent angeben kann, dass auf Informationen im Zusammenhang mit einer Ausgabe über die angegebene Aktion des Links zugegriffen werden kann. Wie bei HTML-Links in einem Webbrowser ermöglicht dies dem Benutzer die Navigation durch hyperlinkierte Informationen.

Ein Vorteil der Bereitstellung von Hyperlinkinhalten besteht darin, dass sie verwendet werden können, um die Auffindbarkeit von Debugger- und Debuggererweiterungsfunktionen zu verbessern. Der Debugger und seine Erweiterungen enthalten eine große Menge an Funktionalität, aber es kann schwierig sein, den geeigneten Befehl für die Verwendung in verschiedenen Szenarien zu bestimmen. Benutzer müssen einfach wissen, welche Befehle in bestimmten Szenarien verwendet werden können. Unterschiede zwischen Benutzer- und Kerneldebuggen erhöhen die Komplexität. Dies bedeutet häufig, dass viele Benutzer keine Debugbefehle wissen, die ihnen helfen könnten. DML-Links bieten die Möglichkeit, beliebige Debugbefehle in alternative Präsentationen umschließen zu können, z. B. beschreibender Text, klickbare Menüsysteme oder verknüpfte Hilfe. Mithilfe von DML kann die Befehlsausgabe erweitert werden, um den Benutzer zu zusätzlichen verwandten Befehlen zu leiten, die für die jeweilige Aufgabe relevant sind.

DML-Unterstützung für Debugger

• Das Befehlsfenster in WinDbg unterstützt das gesamte DML-Verhalten und zeigt Farben, Schriftstile und Links an.
• Die Konsolendebugger – ntsd, cdb und kd – unterstützen nur die Farbattribute von DML und nur, wenn sie in einer echten Konsole mit aktiviertem Farbmodus ausgeführt werden.
• Debugger mit umgeleiteten E/A-, ntsd-d- oder remote.exe-Sitzungen zeigen keine Farben an.

DML-Inhaltsspezifikation

DML ist nicht als vollständige Präsentationssprache wie HTML vorgesehen. DML ist bewusst sehr einfach und verfügt nur über eine Handvoll Tags.

Da nicht alle Debuggertools Rich-Text unterstützen, ist DML so konzipiert, dass es eine einfache Übersetzung zwischen DML und Nur-Text ermöglicht. Dadurch kann DML in allen vorhandenen Debuggertools funktionieren. Effekte wie Farben können problemlos unterstützt werden, da durch deren Entfernung der Text, der die tatsächlichen Informationen enthält, nicht entfernt wird.

DML ist kein XML. DML versucht nicht, semantische oder strukturierte Informationen zu übertragen. Wie oben erwähnt, muss es eine einfache Zuordnung zwischen DML und Nur-Text geben, aus diesem Grund können DML-Tags alle verworfen werden.

DML ist nicht erweiterbar. Alle Tags sind vorab definiert und überprüft, um für alle vorhandenen Debuggertools zu funktionieren.

Tagstruktur

Ähnlich wie XML werden DML-Tags als Starttagname <[args]> und als folgenden </tagname> angegeben.

Sonderzeichen

DML-Inhalte folgen grob den XML/HTML-Regeln für Sonderzeichen. Die Zeichen &, <, > und " sind speziell und können nicht im Nur-Text verwendet werden. Die entsprechenden Escapeversionen sind &, <, > und ". Beispiel:

"Alice & Bob think 3 < 4"

würde in die folgende DML konvertiert werden.

"Alice & Bob think 3 &lt 4"

Formatieren von Zeichen der Programmiersprache C

Eine wesentliche Abkehr von XML/HTML-Regeln besteht darin, dass DML-Text Zeichen im Streamformat der C-Programmiersprache wie \b, \t, \r und \n enthalten kann. Dies ist, um die Kompatibilität mit der vorhandenen Debuggertextproduktion und -verwendung zu unterstützen.

DML-Beispiel

Angenommen, die Datei C:\Dml_Experiment.txt enthält die folgenden Zeilen.

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

Der folgende Befehl zeigt den Text und den Link im Fenster Befehlsbrowser an.

.browse .dml_start c:\Dml_Experiment.txt

Wenn Sie auf den Link Module auflisten klicken, die mit USB beginnen , wird eine Ausgabe ähnlich der folgenden Abbildung angezeigt.

Verhalten mit der rechten Maustaste in DML

Das Verhalten mit der rechten Maustaste ist in DML verfügbar. In diesem Beispiel wird gezeigt, wie Sie das Rechtklickverhalten mithilfe von <altlink> definieren, um einen Breakpoint-Bp-Befehl (Breakpoint festlegen) zu senden und das u (Unassemble) mit einem regulären Klick zu senden.

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

DML-Tagreferenz

<verbinden>

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

Das Linktag ist der grundlegende Hyperlinkmechanismus in DML. Es leitet Benutzeroberflächen an, die die DML-Präsentation unterstützen, um den Linktext als klickbaren Link anzuzeigen. Wenn auf einen Link mit einer cmd-Spezifikation geklickt wird, wird der Debuggerbefehl ausgeführt, und seine Ausgabe sollte die aktuelle Ausgabe ersetzen.

Die Namen- und Abschnittsargumente ermöglichen die Navigation zwischen benannten Links, ähnlich wie html-Name <> und #name Unterstützung. Wenn auf einen Link mit einem Abschnittsargument geklickt wird, sucht die Benutzeroberfläche nach einem Link mit einem übereinstimmenden Namen und scrollt diesen in die Ansicht. Dadurch können Links auf verschiedene Abschnitte derselben Seite (oder einen bestimmten Abschnitt einer neuen Seite) verweisen. Der Abschnittsname von DML ist getrennt, um zu vermeiden, dass eine neue Syntax definiert werden muss, die einen Abschnittsnamen am Ende der Befehlszeichenfolge zulässt.

Bei der Konvertierung in Nur-Text werden die Tags gelöscht.

Beispiel

<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>

Beispiel

Dieses Beispiel zeigt die Verwendung des alt-Attributs zum Erstellen von Text, der angezeigt wird, wenn Sie mit der Maus auf den DML-Link zeigen.

<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>

Das <Altlink-Tag> bietet Rechtsklickverhalten ist in DML verfügbar. Wenn auf einen Link mit einer cmd-Spezifikation geklickt wird, wird der Debuggerbefehl ausgeführt, und seine Ausgabe sollte die aktuelle Ausgabe ersetzen. Die <Registerkarte "Altlink> " wird normalerweise mit dem <Linktag> gekoppelt, um regelmäßiges Und Rechtsklickverhalten zu unterstützen.

Bei der Konvertierung in Nur-Text werden die Tags gelöscht.

Beispiel

In diesem Beispiel wird gezeigt, wie Sie das Rechtklickverhalten mithilfe von <altlink> definieren, um einen Breakpoint-Befehl bp (Breakpoint festlegen) zu senden und das u (Unassemble) mit einem regulären Klick zu senden.

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

<Exec>

<exec cmd="debugger_command">beschreibender Text</exec>

Ein exec-Tag ähnelt einem Linktag, da der beschreibende Text als klickbares Element dargestellt werden soll. Wenn das exec-Tag jedoch in einem Befehlsbrowserfenster verwendet wird, wird der angegebene Befehl ausgeführt, ohne die aktuelle Ausgabe zu ersetzen, bietet dieses Tag eine Möglichkeit, Befehle mit einem Klick aus einem Menü auszuführen.

Bei der Konvertierung in Nur-Text werden die Tags gelöscht.

Beispiel

In diesem Beispiel wird gezeigt, wie Sie zwei Befehle mit einem regulären Klick definieren.

<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>fett formatierter Text</b>

Dieses Tag fordert Fett an. Die <b>, <i> und <u> können geschachtelt werden, um eine Mischung aus den Eigenschaften zu erhalten.

Bei der Konvertierung in Nur-Text werden die Tags gelöscht.

Beispiel

In diesem Beispiel wird gezeigt, wie Text fett formatiert wird.

<b>This is bold Text</b>

<Ich>

<i>Kursivtext</i>

Dieses Tag fordert Kursiv an. Die <b>, <i> und <u> können geschachtelt werden, um eine Mischung aus den Eigenschaften zu erhalten.

Bei der Konvertierung in Nur-Text werden die Tags gelöscht.

Beispiel

In diesem Beispiel wird gezeigt, wie Text kursiv wird.

<i>This is italicized Text</i>

<U>

<u>unterstrichener Text</u>

Dieses Tag fordert unterstrichenen Text an. Die <b>, <i> und <u> können geschachtelt werden, um eine Mischung aus den Eigenschaften zu erhalten.

Bei der Konvertierung in Nur-Text werden die Tags gelöscht.

Beispiel

In diesem Beispiel wird gezeigt, wie Text unterstrichen wird.

<u>This is underlined Text</u>

Beispiel

In diesem Beispiel wird gezeigt, wie Sie Tags zu Fett, Unterstrichen und Kursivierung von Text kombinieren.

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

<Col>

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

Fordern Sie Vordergrund- und Hintergrundfarben für den Text an. Die Farben werden als Namen bekannter Farben anstelle von absoluten Werten angegeben, da Kunden steuern können, welche Art von Farbe sie sehen. Aktuelle Farbnamen (Standardwerte gelten nur für WinDbg).

Vordergrund- und Hintergrundelementtags

Einstellung	Beschreibung/Beispiel
wbg – Windows-Hintergrund wfg – Windows-Vordergrund	Standardmäßige Hintergrund- und Vordergrundfarben des Fensters. Standardmäßig werden Systemfarben für Fenster- und Fenstertext verwendet. <col fg="wfg" bg="wbg"> Dies ist Standardtext im Vordergrund/Hintergrundtext </col>
clbg – Aktueller Zeilen-Vordergrund clfg – Aktueller Zeilenhintergrund	Aktuelle Linienhintergrund- und Vordergrundfarben. Standardmäßig werden Systemfarben für Text hervorgehoben und hervorgehoben. <col fg="clfg" bg="clbg"> Testtext – Current Line</col>
empbg – Hervorgehobener Hintergrund emphfg – Hervorgehobener Vordergrund	Hervorgehobener Text. Standardmäßig ist hellblau festgelegt. <col fg="empfg" bg="empbg"> This is emphasis foreground /background text </col>
subbg – Subduzierter Hintergrund subfg: Subdued foreground	Subduzierter Text. Standardfarbe für inaktiven Untertitel Text und inaktive Beschriftungen. <col fg="subfg" bg="subbg"> This is subdued foreground /background text </col>
normbg – Normaler Hintergrund normfg – Normaler Vordergrund	Normal <col fg="normfg" bg="normbg"> Testtext - Normal (normfg / normbg) </col>
warnbg – Warnungshintergrund warnfg – Warnungs-Vordergrund	Warnung <col fg="warnfg" bg="warnbg"> Testtext – Warnung (warnfg / warnbg) </col>
errbg – Fehlerhintergrund errfg : Fehler im Vordergrund	Fehler <col fg="errfg" bg="errbg"> Testtext - Error (errfg / errbg) </col>
verbbg – Ausführlicher Hintergrund verbfg – Ausführlicher Vordergrund	Ausführlich <col fg="verbfg" bg="verbbg"> Testtext - Verbose (verbfg / verbbg) </col>

Source Code Single Element Tags

srcnum – Numerische Quellkonstante	Quellelementfarben. <col fg="srcnum" bg="wbg"> Testtext - srcnum </col>
srcchar – Quellzeichenkonstante	<col fg="srcchar" bg="wbg"> Testtext - srcchar </col>
srcstr – Quellzeichenfolgenkonstante	<col fg="srcstr" bg="wbg"> Testtext - srcstr </col>
srcid -Source-Bezeichner	<col fg="srcid " bg="wbg"> Testtext - srcid </col>
srckw- Schlüsselwort	<col fg="srckw" bg="wbg"> Testtext - srckw </col>
srcpair : Quellklammer oder übereinstimmende Symbolpaar	<col fg="srcpair" bg="empbbg"> Testtext - srcpair </col>
srccmnt – Quellkommentar	<col fg="srccmnt" bg="wbg"> Testtext - srccmnt </col>
srcdrct – Quelldirektive	<col fg="srcdrct" bg="wbg"> Testtext - srcdrct </col>
srcspid – Spezieller Quellbezeichner	<col fg="srcspid" bg="wbg"> Testtext - srcspid </col>
srcannot – Quellanmerkung	<col fg="srcannot" bg="wbg"> Testtext - srcannot </col>
geändert: Geänderte Daten	Wird für Daten verwendet, die sich seit einem vorherigen Stopppunkt geändert haben, z. B. geänderte Register in WinDbg. Standardmäßig wird rot festgelegt. <col fg="changed" bg="wbg"> Testtext – Changed</col>

DML-Beispielcode

Dieser Beispielcode veranschaulicht Folgendes.

• Aufrufen von Debugbefehlen
• Implementieren von Rechtsklickbefehlen
• Implementieren des Mauszeigers auf Text
• Verwenden von Farbe und Rich Text

<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

Dieser Beispielcode veranschaulicht die Verwendung von Farb- und Formatierungstags.

*** 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>

DML-Ergänzungen zur dbgeng-Schnittstelle

Die Debugger-Engine und erweiterungs-APIs bieten eine Schnittstelle zum Erstellen benutzerdefinierter Anwendungen mit der Debugger-Engine. Sie können auch benutzerdefinierte Erweiterungen schreiben, die in WinDbg, KD, CDB und NTSD ausgeführt werden. Weitere Informationen finden Sie unter Schreiben von DbgEng-Erweiterungen. In diesem Abschnitt werden die verfügbaren DML-Erweiterungen für die Schnittstellen der Debugger-Engine beschrieben.

Der dbgeng verfügt bereits über eine Reihe von Textverarbeitungsmethoden und Ausgabeschnittstellen. Für die Verwendung von DML ist nur die Angabe des Inhaltstyps erforderlich, der im Eingabe- und Ausgabetext übertragen wird.

Bereitstellen von DML-Inhalten für dbgeng

Das Ausgabesteuerelementflag DEBUG_OUTCTL_DML gibt an, dass der von einer dbgeng-Methode generierte Text als DML-Inhalt behandelt werden soll. Wenn dieses Flag nicht angegeben wird, wird der Text als Nur-Text-Kontext behandelt. DEBUG_OUTCTL_DML können mit den folgenden Methoden verwendet werden.

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

Der angegebene Text muss den DML-Regeln für gültige Zeichen entsprechen.

Alle Ausgaberoutinen wurden erweitert, um einen neuen Formatbezeichner %[h|w]Y{t} zu ermöglichen. Dieser Formatbezeichner verfügt über einen Zeichenfolgenzeiger als Argument und gibt an, dass der angegebene Text Nur-Text ist und während der Ausgabeverarbeitung in das DML-Format konvertiert werden soll. Dadurch erhalten Aufrufer eine einfache Möglichkeit, Nur-Text in DML-Inhalte einzuspeichern, ohne selbst in das DML-Format vorkonvertieren zu müssen. Die h- und w-Qualifizierer geben ANSI- oder Unicode-Text an, wie bei %s.

In der folgenden Tabelle wird die Verwendung des Formatbezeichners %Y zusammengefasst.

%Y{t}: Zeichenfolge in Anführungszeichen. Konvertiert Text in DML, wenn das Ausgabeformat (erster Arg) DML ist.

%Y{T}: Zeichenfolge in Anführungszeichen. Konvertiert Text immer in DML, unabhängig vom Ausgabeformat.

%Y{s}: Zeichenfolge ohne Anführungszeichen. Konvertiert Text in DML, wenn das Ausgabeformat (erster Arg) DML ist.

%Y{S}: Zeichenfolge ohne Anführungszeichen. Konvertiert Text immer in DML, unabhängig vom Ausgabeformat.

%Y{as}: ULONG64. Fügt entweder eine leere Zeichenfolge oder 9 Zeichen Abstand zum Auffüllen des hohen 32-Bit-Teils der debuggerformatierten Zeigerfelder hinzu. Das zusätzliche Leerzeichen gibt 9 Leerzeichen aus, die die oberen 8 Nullen plus das Zeichen " enthalten.

%Y{ps}: ULONG64. Zusätzlicher Platz für das Auffüllen debuggerformatierter Zeigerfelder (enthält die oberen 8 Nullen plus das Zeichen ' ).

%Y{l}: ULONG64. Adresse als Quellzeileninformationen.

Dieser Codeausschnitt veranschaulicht die Verwendung des %Y-Formatbezeichners.

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;

}

Dieser Beispielcode würde die folgende Ausgabe generieren.

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]

Ein zusätzliches Steuerelementflag, DEBUG_OUTCTL_AMBIENT_DML, ermöglicht die Spezifikation von DML-Kontexttext, ohne die Ausgabesteuerelementattribute zu ändern. DEBUG_OUTCTL_AMBIENT_TEXT wurde auch als aussagekräftigerer Alias für die zuvor vorhandene DEBUG_OUTCTL_AMBIENT hinzugefügt. Die Ausgabesteuerungsflags sind in dbgeng.h definiert.

#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

Bereitstellen von DML-Inhalten aus einem Debuggee

Der dbgeng wurde verbessert, um die Debuggee-Ausgabe für einen speziellen Marker zu überprüfen, der angibt, dass der verbleibende Text in einer Debuggee-Ausgabe als DML behandelt werden soll. Die Modusänderung gilt nur für eine einzelne Debugausgabe, z. B. eine einzelne OutputDebugString-Zeichenfolge, und ist kein globaler Modusswitch.

Dieses Beispiel zeigt eine Mischung aus einfacher und DML-Ausgabe.

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

Die erzeugte Ausgabe enthält eine Zeile mit Nur-Text, gefolgt von einer Zeile mit DML, in der das Akronym DML in einer anderen Farbe angezeigt wird.

IDebugOutputCallbacks2

IDebugOutputCallbacks2 ermöglicht dbgeng-Schnittstellenclients, vollständige DML-Inhalte zur Präsentation zu empfangen. IDebugOutputCallbacks2 ist eine Erweiterung von IDebugOutputCallbacks (nicht IDebugOutputCallbacksWide), sodass sie an die vorhandene SetOutputCallbacks-Methode übergeben werden kann. Die Engine führt ein QueryInterface für IDebugOutputCallbacks2 aus, um zu sehen, welche Schnittstelle das eingehende Ausgaberückrufobjekt unterstützt. Wenn das Objekt IDebugOutputCallbacks2 unterstützt, wird die gesamte Ausgabe über die erweiterten IDebugOutputCallbacks2-Methoden gesendet. Die grundlegende IDebugOutputCallbacks::Output-Methode wird nicht verwendet.

Die neuen Methoden sind:

• IDebugOutputCallbacks2::GetInterestMask – Ermöglicht dem Rückrufobjekt, zu beschreiben, welche Arten von Ausgabebenachrichtigungen empfangen werden sollen. Die grundlegende Wahl ist zwischen Nur-Text-Inhalt (DEBUG_OUTCBI_TEXT) und DML-Inhalt (DEBUG_OUTCBI_DML). Darüber hinaus kann das Rückrufobjekt auch eine Benachrichtigung über explizite Leerungen (DEBUG_OUTCBI_EXPLICIT_FLUSH) anfordern.

• IDebugOutputCallbacks2::Output2 – Alle IDebugOutputCallbacks2-Benachrichtigungen kommen über Output2. Der Parameter Which gibt an, welche Art von Benachrichtigung eingeht, während die Parameter Flags, Arg und Text die Benachrichtigungsnutzlast enthalten. Zu den Benachrichtigungen gehören:

  • DEBUG_OUTCB_TEXT – Nur-Text-Ausgabe. Flags stammen von DEBUG_OUTCBF_*, Arg ist das Ausgabeformat und Text ist der Nur-Text. Diese wird nur empfangen, wenn DEBUG_OUTCBI_TEXT in der Interessenmaske angegeben wurde.

  • DEBUG_OUTCB_DML – Ausgabe des DML-Inhalts. Flags stammen von DEBUG_OUTCBF_*, Arg ist das Ausgabeformat und Text ist der DML-Inhalt. Diese wird nur empfangen, wenn DEBUG_OUTCBI_DML in der Interessenmaske angegeben wurde.

  • DEBUG_OUTCB_EXPLICIT_FLUSH : Ein Aufrufer hat FlushCallbacks ohne gepufferten Text aufgerufen. Wenn gepufferter Text geleert wird, wird normalerweise das DEBUG_OUTCBF_COMBINED_EXPLICIT_FLUSH-Flag festgelegt, wobei die beiden Benachrichtigungen in eine Benachrichtigung gefaltet werden. Wenn kein Text gepuffert wird, wird eine Benachrichtigung gesendet, die nur leer ist.

Die Interessenmaskenflags sind in dbgeng.h definiert, wie hier gezeigt.

// 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

Beachten Sie, dass sich ein Ausgabeobjekt sowohl für Text als auch für DML-Inhalt registrieren kann, wenn es beide verarbeiten kann. Während der Ausgabeverarbeitung des Rückrufs wählt die Engine das Format aus, das Konvertierungen reduziert, sodass die Unterstützung beider Konvertierungen die Konvertierungen in der Engine reduzieren kann. Es ist jedoch nicht erforderlich, und die Unterstützung nur eines Formats ist die erwartete Betriebsart.

Automatische Konvertierungen

Der dbgeng konvertiert bei Bedarf automatisch zwischen Nur-Text und DML. Wenn beispielsweise ein Aufrufer DML-Inhalt an die Engine sendet, konvertiert die Engine diesen für alle Ausgabeclients, die nur Nur-Text akzeptieren, in Nur-Text. Alternativ konvertiert die Engine für alle Ausgaberückrufe, die nur DML akzeptieren, Nur-Text in DML.

Siehe auch

Verwenden der Debuggermarkupsprache