使用 DML 自訂除錯程序輸出

發行項
01/10/2024

調試程式標記語言 (DML) 提供一種機制來增強調試程式和延伸模組的輸出。與 HTML 類似，調試程式的標記支援允許輸出在標記形式中包含顯示指示詞和額外的非顯示資訊。調試程式使用者介面，例如 WinDbg 會剖析 DML 中提供的額外資訊，以增強信息的顯示，並提供新的行為，例如方格顯示和排序。本主題描述如何使用 DML 自定義偵錯輸出。如需在調試程式中啟用和使用 DML 的一般資訊，請參閱使用調試程式標記語言。

DML 可在 Windows 10 和更新版本中使用。

DML 概觀

在 DML 的主要優點上，它提供連結至調試程式輸出中相關信息的能力。其中一個主要 DML 標記是 <連結> 標記，可讓輸出產生者指出可以透過連結的陳述動作來存取與輸出片段相關的資訊。如同網頁瀏覽器中的 HTML 連結，這可讓使用者瀏覽超連結資訊。

提供超連結內容的優點是可用來增強調試程式和調試程序擴充功能的可探索性。調試程式和其擴充功能包含大量的功能，但很難判斷要用於不同案例的適當命令。用戶必須只知道哪些命令可用於特定案例。使用者和核心偵錯之間的差異會增加進一步的複雜度。這通常表示許多使用者都不知道可協助它們的偵錯命令。 DML 連結可讓您將任意偵錯命令包裝在替代簡報中，例如描述性文字、可點選功能表系統或鏈接的說明。使用 DML 時，可以增強命令輸出，以引導使用者前往與手邊工作相關的其他相關命令。

調試程式 DML 支援

WinDbg 中的命令窗口支援所有 DML 行為，並會顯示色彩、字型樣式和連結。
主控台除錯程式 – ntsd、cdb 和 kd – 僅支援 DML 的色彩屬性，以及在已啟用色彩模式的 true 控制台中執行時才支援。
具有重新導向 I/O、ntsd –d 或 remote.exe 工作階段的調試程式將不會顯示任何色彩。

DML 內容規格

DML 不是完整的呈現語言，例如 HTML。 DML 刻意非常簡單，而且只有少數標記。

由於並非所有調試程式工具都支援 RTF，因此 DML 的設計目的是允許 DML 與純文本之間的簡單翻譯。這可讓 DML 在所有現有的調試程式工具中運作。可輕易支援色彩之類的效果，因為移除它們並不會移除帶有實際信息的文字。

DML 不是 XML。 DML 不會嘗試攜帶語意或結構化資訊。如上所述，DML 與純文本之間必須有簡單的對應，因此 DML 標籤都是可捨棄的。

DML 不可延伸;所有標記都會預先定義並經過驗證，以在所有現有的調試程式工具之間運作。

標記結構

與 XML 類似，DML 標記會指定為起始 <標記名稱 [args]> 和下列 </tagname>。

特殊字元

DML 內容大致遵循特殊字元的 XML/HTML 規則。字元 &、 <> 和「是特殊字元，不能用在純文字中。對等的逸出版本 &、 <> 和 “ 。例如，此文字：

“Alice & Bob 認為 3 < 4”

會轉換成下列 DML。

"Alice & Bob think 3 &lt 4"

C 程式設計語言格式字元

與 XML/HTML 規則有顯著的差異，就是 DML 文字可以包含 C 程式設計語言數據流樣式格式字元，例如 \b、\t、\r 和 \n。這是為了支援與現有調試程式文字生產與耗用量的相容性。

範例 DML

假設檔案 C:\Dml_Experiment.txt 包含下列幾行。

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

下列命令會顯示 [命令瀏覽器] 視窗中的文字和連結。

.browse .dml_start c:\Dml_Experiment.txt

命令瀏覽器視窗中 DML 檔案輸出的螢幕快照。

如果您按下 以 usb 連結開頭的清單模組 ，您會看到類似下圖的輸出。

按兩下 DML 輸出中的連結之後，模組清單的螢幕快照。

在 DML 中以滑鼠右鍵按兩下行為

DML 中有可用的按兩下滑鼠右鍵行為。此範例示範如何使用 altlink 定義滑鼠右鍵行為，以使用 <altlink> 傳送斷 點 bp (Set Breakpoint) 命令，並使用一般點選傳送 u (Unassemble) 。

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

DML 標籤參考

<連結>

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

連結標籤是 DML 中的基本超鏈接機制。它會指示支援 DML 簡報的使用者介面，將連結文字顯示為可點選的連結。按兩下 Cmd 規格的連結時，除錯程式命令會執行，而且其輸出應該取代目前的輸出。

名稱和區段自變數允許在具名連結之間瀏覽，類似於 HTML <的名稱> 和 #name 支援。當UI上按兩下具有區段自變數的連結時，會掃描名為且具有相符名稱的連結，並將該連結卷動到檢視中。這可讓連結指向相同頁面的不同區段 (或新頁面) 的特定區段。 DML 的區段名稱是分開的，以避免必須定義新的語法，以允許命令字串結尾的區段名稱。

轉換成純文本會卸除標記。

範例

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

範例

此範例示範如何使用alt屬性來建立當您將滑鼠停留在 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>

<altlink> 標籤提供 DML 中可用的單擊滑鼠右鍵行為。按兩下 Cmd 規格的連結時，除錯程式命令會執行，而且其輸出應該取代目前的輸出。 <altlink> 索引標籤通常會與<連結>標籤配對，以支援一般並按兩下滑鼠右鍵行為。

轉換成純文本會卸除標記。

範例

此範例示範如何使用 altlink> 定義滑鼠右鍵行為，以傳送<斷點 bp (Set Breakpoint) 命令，並使用一般點選傳送 u (Unassemble) 。

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

<Exec>

<exec cmd=“debugger_command”>描述性文字</exec>

exec 標籤類似於連結標籤，描述性文字應該顯示為可點選的專案。不過，在命令瀏覽器視窗中使用 exec 標籤時，會執行指定的命令，而不取代目前的輸出，這個標記會提供一種方式，讓命令以按下的方式執行。

轉換成純文本會卸除標記。

範例

此範例示範如何使用一般按兩下來定義兩個命令。

<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>This is bold Text</b>

<我>

斜體文字

此標籤會要求斜體。 、 和 可以巢狀化，以混合屬性。

轉換成純文本會卸除標記。

範例

此範例示範如何斜體文字。

<i>This is italicized Text</i>

<美國>

底線文字

此標籤會要求加底線文字。 、 和 可以巢狀化，以混合屬性。

轉換成純文本會卸除標記。

範例

此範例示範如何加上底線的文字。

<u>This is underlined Text</u>

範例

此範例示範如何將標記結合為粗體、底線和斜體文字。

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

<col>

要求文字的前景和背景色彩。色彩會指定為已知色彩的名稱，而不是絕對值，讓客戶能夠控制他們看到的色彩類型。目前的色彩名稱 (預設值僅適用於 WinDbg) 。

前景和背景元素標記

設定	說明/範例
wbg - Windows 背景 wfg - Windows 前景	默認視窗背景和前景色彩。預設為視窗和視窗文字的系統色彩。 <col fg=“wfg” bg=“wbg”> 這是標準前景/背景文字 </col>
clbg - 目前線條前景 clfg - 目前行背景	目前線條背景和前景色彩。預設為醒目提示和醒目提示文字的系統色彩。 <col fg=“clfg” bg=“clbg”> Test Text - Current Line</col>
empbg - 強調的背景 emphfg - 強調前景	強調文字。默認為淺藍色。 <col fg=“empfg” bg=“empbg”> 這是強調前景/背景文字 </col>
subbg - Subdued 背景 subfg- 子工時前景	已減去的文字。預設為非使用中標題文字和非使用中標題的系統色彩。 <col fg=“subfg” bg=“subbg”> 這是子前景/背景文字 </col>
normbg - 一般背景 normfg - 一般前景	正常 <col fg=“normfg” bg=“normbg”> 測試文字 - 一般 (normfg / normbg) </col>
warnbg - 警告背景 warnfg - 警告前景	警告 <col fg=“warnfg” bg=“warnbg”> 測試文字 - 警告 (warnfg / warnbg) </col>
errbg - 錯誤背景 errfg - 前景錯誤	錯誤 <col fg=“errfg” bg=“errbg”> 測試文字 - 錯誤 (errfg / errbg) </col>
verbbg - 詳細資訊背景 verbfg - 詳細資訊前景	「詳細資訊」 <col fg=“verbfg” bg=“verbbg”> Test Text - Verbose (verbfg / verbbg) </col>

原始碼單一元素標記

srcnum - 來源數值常數	來源元素色彩。 <col fg=“srcnum” bg=“wbg”> Test Text - srcnum </col>
srcchar - 來源字元常數	<col fg=“srcchar” bg=“wbg”> Test Text - srcchar </col>
srcstr - 來源字串常數	<col fg=“srcstr” bg=“wbg”> Test Text - srcstr </col>
srcid -來源標識符	<col fg=“srcid ” bg=“wbg”> Test Text - srcid </col>
srckw- 關鍵詞	<col fg=“srckw” bg=“wbg”> Test Text - srckw </col>
srcpair - 來源大括弧或相符符號組	<col fg=“srcpair” bg=“empbbg”> 測試文字 - srcpair </col>
srccmnt - 來源批注	<col fg=“srccmnt” bg=“wbg”> Test Text - srccmnt </col>
srcdrct - 來源指示詞	<col fg=“srcdrct” bg=“wbg”> 測試文字 - srcdrct </col>
srcspid - 來源特殊識別符	<col fg=“srcspid” bg=“wbg”> Test Text - srcspid </col>
srcannot - 來源批注	<col fg=“srcannot” bg=“wbg”> 測試文字 - srcannot </col>
已變更 - 已變更數據	用於自先前停止點以來已變更的數據，例如 WinDbg 中的變更緩存器。默認為紅色。 <col fg=“changed” bg=“wbg”> Test Text - Changed</col>

DML 範例程序代碼

此範例程式代碼說明下列各項。

呼叫偵錯命令
實作以滑鼠右鍵按下命令
實作將滑鼠停留在文字上方
使用色彩和 RTF

<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

此範例程式代碼說明如何使用色彩和格式標記。

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

dbgeng 介面的 DML 新增專案

調試程式引擎和擴充功能 API 提供介面，以使用調試程式引擎來建立自定義應用程式。您也可以撰寫將在 WinDbg、KD、CDB 和 NTSD 中執行的自定義延伸模組。如需詳細資訊，請參閱撰寫 DbgEng 延伸模組。本節說明調試程式引擎介面的可用 DML 增強功能。

dbgeng 已經有一組文字處理輸入方法和輸出介面，使用 DML 只需要輸入和輸出文字中所攜帶內容類型的規格。

將 DML 內容提供給 dbgeng

輸出控件旗標DEBUG_OUTCTL_DML表示 dbgeng 方法所產生的文字應該處理為 DML 內容。如果未指定此旗標，則會將文字視為純文本內容。 DEBUG_OUTCTL_DML可以搭配下列方法使用。

指定的文字必須遵循有效字元的 DML 規則。

所有輸出例程都已增強，以允許新的格式規範 %[h|w]Y{t}。此格式規範具有字串指標做為自變數，並指出指定的文字是純文本，而且應該在輸出處理期間轉換成 DML 格式。這可讓呼叫端以簡單的方式在 DML 內容中包含純文字，而不需要預先轉換成 DML 格式本身。 h 和 w 限定符表示 ANSI 或 Unicode 文字，如同 %s。

下表摘要說明 %Y 格式規範的使用方式。

%Y{t}：引號字串。如果輸出格式 (第一個自變數) 為 DML，則會將文字轉換成 DML。

%Y{T}：引號字串。不論輸出格式為何，一律會將文字轉換成 DML。

%Y{s}：未加上批註的字串。如果輸出格式 (第一個自變數) 為 DML，則會將文字轉換成 DML。

%Y{S}：未加上批註的字串。不論輸出格式為何，一律會將文字轉換成 DML。

%Y{as}： ULONG64。新增空字串或 9 個字元的間距，以填補調試程式格式化指標欄位的高 32 位部分。額外的空間會輸出 9 個空格，其中包含前 8 個零加上 ' 字元。

%Y{ps}： ULONG64。填補調試程式格式化指標字段的額外空間 (包含前 8 個零加上 ' 字元) 。

%Y{l}： ULONG64。以源行資訊作為位址。

此代碼段說明如何使用 %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;

}

此範例程式代碼會產生下列輸出。

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]

其他控件旗標DEBUG_OUTCTL_AMBIENT_DML允許 DML 內容文字的規格，而不需修改任何輸出控件屬性。 DEBUG_OUTCTL_AMBIENT_TEXT也已新增為先前現有DEBUG_OUTCTL_AMBIENT的更描述性別名。輸出控件旗標定義於 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

從偵錯提供 DML 內容

dbgeng 已增強以掃描特殊標記的偵錯輸出 – 表示偵錯輸出片段中的其餘文字應該視為 DML。模式變更只適用於單一偵錯輸出片段，例如單一 OutputDebugString 字串串，而且不是全域模式參數。

此範例示範一般和 DML 輸出的混合。

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

產生的輸出會有一行純文本，後面接著一行 DML，其中縮略字 DML 會以不同的色彩顯示。

IDebugOutputCallbacks2

IDebugOutputCallbacks2 可讓 dbgeng 介面用戶端接收完整的 DML 內容以供簡報使用。 IDebugOutputCallbacks2 是 IDebugOutputCallbacks 的延伸模組， (不是 IDebugOutputCallbacksWide) ，以便它可以傳入現有的 SetOutputCallbacks 方法。引擎會執行適用於 IDebugOutputCallbacks2 的 QueryInterface，以查看傳入輸出回呼物件支援的介面。如果物件支援 IDebugOutputCallbacks2，所有輸出都會透過擴充的 IDebugOutputCallbacks2 方法傳送;不會使用基本 IDebugOutputCallbacks：：Output 方法。

新的方法包括：

IDebugOutputCallbacks2：：GetInterestMask – 允許回呼物件描述其想要接收的輸出通知類型。基本選擇是在純文本內容 (DEBUG_OUTCBI_TEXT) 與 DML 內容之間 (DEBUG_OUTCBI_DML) 。此外，回呼物件也可以要求明確排清的通知 (DEBUG_OUTCBI_EXPLICIT_FLUSH) 。
IDebugOutputCallbacks2：：Output2 – 所有 IDebugOutputCallbacks2 通知都通過 Output2。「哪一個」參數表示旗標、Arg 和 Text 參數會攜帶通知承載時，傳入何種通知。通知包括：
- DEBUG_OUTCB_TEXT – 純文字輸出。旗標來自DEBUG_OUTCBF_*，Arg 是輸出遮罩，而 Text 是純文本。只有在相關遮罩中提供DEBUG_OUTCBI_TEXT時，才會收到此專案。
- DEBUG_OUTCB_DML – DML 內容輸出。旗標來自DEBUG_OUTCBF_*，Arg 是輸出遮罩，而 Text 是 DML 內容。只有在感興趣的遮罩中提供DEBUG_OUTCBI_DML時，才會收到此專案。
- DEBUG_OUTCB_EXPLICIT_FLUSH – 呼叫端已呼叫 FlushCallbacks，沒有緩衝的文字。一般而言，當緩衝文字排清時，將會設定DEBUG_OUTCBF_COMBINED_EXPLICIT_FLUSH旗標，將兩個通知折疊成一個。如果未緩衝處理任何文字，則會傳送僅限排清通知。

興趣遮罩旗標定義於 dbgeng.h 中，如下所示。

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

請注意，如果輸出物件可以同時處理這兩個文字和 DML 內容，則可以註冊它們。在回呼的輸出處理期間，引擎會挑選可減少轉換的格式，因此支援這兩者可能會減少引擎中的轉換。不過，不需要支援一種格式是預期的作業模式。

自動轉換

dbgeng 會視需要自動在純文本與 DML 之間轉換。例如，如果呼叫端將 DML 內容傳送至引擎，引擎會針對只接受純文字的所有輸出用戶端，將它轉換成純文本。或者，引擎會針對只接受 DML 的所有輸出回呼，將純文本轉換成 DML。

另請參閱

使用調試程式標記語言

使用 DML 自訂除錯程序輸出

DML 概觀

DML 內容規格

範例 DML

在 DML 中以滑鼠右鍵按兩下行為

DML 標籤參考

<連結>

<altlink>

<Exec>

<B>

<我>

<美國>

<col>

DML 範例程序代碼

dbgeng 介面的 DML 新增專案

另請參閱

意見反應

意見反應

其他資源