DML を使用したデバッガー出力のカスタマイズ

デバッガー マークアップ言語 (DML) は、デバッガーと拡張機能からの出力を拡張するためのメカニズムを提供します。 HTML と同様に、デバッガーのマークアップ サポートにより、出力に表示ディレクティブや追加の非表示情報をタグの形式で含めることができます。 WinDbg などのデバッガー ユーザー インターフェイスは、DML で提供される追加情報を解析して情報の表示を強化し、グリッド表示や並べ替えなどの新しい動作を提供します。 このトピックでは、DML を使用してデバッグ出力をカスタマイズする方法について説明します。 デバッガーでの DML の有効化とその使用に関する一般的な情報については、「デバッガー マークアップ言語の使用」を参照してください。

DML は Windows 10 以降で使用できます。

DML の概要

DML の主な利点の 1 つは、デバッガー出力内の関連情報にリンクできる機能を提供することです。 プライマリ DML タグの 1 つは<link> タグです。これにより、出力プロデューサーは、出力の一部に関連する情報にリンクの指定されたアクションを介してアクセスできることを示すことができます。 Web ブラウザーの HTML リンクと同様に、ユーザーはハイパーリンクされた情報を移動できます。

ハイパーリンクされたコンテンツを提供する利点は、それを使用してデバッガーおよびデバッガー拡張機能の発見しやすさを向上できることです。 デバッガーとその拡張機能には大量の機能が含まれていますが、さまざまなシナリオで使用する適切なコマンドを判断するのが難しい場合があります。 ユーザーは、特定のシナリオで使用できるコマンドを知っている必要があります。 ユーザーとカーネルのデバッグの違いにより、さらに複雑になります。 これは多くの場合、多くのユーザーが役立つデバッグ コマンドを知らないことを意味します。 DML リンクにより、任意のデバッグ コマンドを、説明テキスト、クリック可能なメニュー システム、リンクされたヘルプなどの代替プレゼンテーションにラップする機能が提供されます。 DML を使用すると、コマンド出力を拡張して、現在のタスクに関連する追加の関連コマンドにユーザーをガイドできます。

デバッガーの DML サポート

• WinDbg のコマンド ウィンドウはすべての DML 動作をサポートし、色、フォント スタイル、およびリンクを表示します。
• コンソール デバッガー (ntsd、cdb、および kd) は DML のカラー属性のみをサポートし、カラー モードが有効になっている真のコンソールで実行されている場合にのみサポートします。
• リダイレクトされた I/O、ntsd –d、または remote.exe セッションを持つデバッガーでは、色は表示されません。

DML コンテンツの仕様

DML は、HTML などの完全なプレゼンテーション言語を意図したものではありません。 DML は意図的に非常にシンプルで、数個のタグしかありません。

すべてのデバッガ ツールがリッチ テキストをサポートしているわけではないため、DML は DML とプレーン テキストの間で簡単に変換できるように設計されています。 これにより、DML が既存のすべてのデバッガー ツールで機能できるようになります。 色などの効果は、それらを削除しても実際の情報を含むテキストは削除されないため、簡単にサポートできます。

DML は XML ではありません。 DML は、セマンティック情報や構造化情報を伝達しようとしません。 前述したように、DML とプレーン テキストの間には単純なマッピングが必要です。このため、DML タグはすべて破棄可能です。

DML は拡張可能ではありません。すべてのタグは事前定義されており、既存のすべてのデバッガー ツールで機能することが検証されています。

タグの構造

XML と同様に、DML タグは開始 <tagname [args]> と次の < /tagname> として指定されます。

特殊文字

DML コンテンツは、特殊文字の XML/HTML 規則にほぼ従います。 文字 &、<、>、および " は特殊文字であり、プレーンテキストでは使用できません。 同等のエスケープされたバージョンは、&、<、>、および " です。 たとえば、次のテキストを使用します。

"Alice & Bob think 3 < 4"

は、次の DML に変換されます。

"Alice & Bob think 3 &lt 4"

C プログラミング言語の書式設定文字

XML/HTML ルールからの大きな違いは、DML テキストに \b、\t、\r、\n などの C プログラミング言語のストリーム スタイルの書式設定文字を含めることができることです。 これは、既存のデバッガー テキストの生成と使用との互換性をサポートするためです。

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

usb で始まる List モジュール リンクをクリックすると、次の図のような出力が表示されます。

DML の右クリック動作

右クリック動作は DML で使用できます。 このサンプルでは、<altlink> を使用して右クリック動作を定義し、bp (ブレークポイントの設定) コマンドを送信し、通常のクリックで u (逆アセンブル) を送信する方法を示します。

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

DML タグ参照

<link>

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

リンク タグは、DML の基本的なハイパー リンク メカニズムです。 DML プレゼンテーションをサポートするユーザー インターフェイスに、リンク テキストをクリック可能なリンクとして表示するように指示します。 cmd 仕様を含むリンクをクリックすると、デバッガー コマンドが実行され、その出力が現在の出力と置き換わります。

名前とセクションの引数を使用すると、HTML の<a name> や #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> タブは通常、<link> タグと組み合わせて、通常の右クリック動作をサポートします。

プレーン テキストに変換すると、タグが削除されます。

例

この例では、<altlink> を使用して右クリック動作を定義し、bp (ブレークポイントの設定) コマンドを送信し、通常のクリックで u (逆アセンブル) を送信する方法を示します。

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

<exec>

<exec cmd=”debugger_command”>descriptive text</exec>

exec タグは、説明テキストがクリック可能な項目として表示されるという点で link タグに似ています。 ただし、コマンド ブラウザー ウィンドウで exec タグを使用すると、現在の出力を置き換えずに指定されたコマンドが実行されます。このタグは、メニューからクリックするだけでコマンドを実行することができます。

プレーン テキストに変換すると、タグが削除されます。

例

この例では、通常のクリックで 2 つのコマンドを定義する方法を示します。

<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>太字テキスト</b>

このタグは太字を要求します。 <b>、 <i>、および <u> は、入れ子にして、プロパティを組み合わせることができます。

プレーン テキストに変換すると、タグが削除されます。

例

この例では、テキストを太字にする方法を示します。

<b>This is bold Text</b>

<i>

<i>斜体テキスト</i>

このタグは斜体を要求します。 <b>、 <i>、および <u> は、入れ子にして、プロパティを組み合わせることができます。

プレーン テキストに変換すると、タグが削除されます。

例

この例では、テキストを斜体にする方法を示します。

<i>This is italicized Text</i>

<u>

<u>下線付きテキスト</u>

このタグは、下線付きテキストを要求します。 <b>、 <i>、および <u> は、入れ子にして、プロパティを組み合わせることができます。

プレーン テキストに変換すると、タグが削除されます。

例

この例では、テキストを下線付きにする方法を示します。

<u>This is underlined Text</u>

例

この例では、タグを太字、下線、斜体に結合する方法を示します。

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

<col>

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

テキストの前景色と背景色を要求します。 色は絶対値ではなく既知の色の名前として指定されるため、ユーザーは表示する色の種類を制御できます。 現在の色名 (既定値は WinDbg にのみ適用されます)。

前景要素タグと背景要素タグ

ソース コードの単一要素タグ

DML のコード例

このコード例は次のことを示しています。

• デバッグ コマンドの呼び出し
• 右クリック コマンドの実装
• テキストの上にマウス ポインターを置く実装
• 色とリッチ テキストの使用

<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 を使用するには、入力テキストと出力テキストに含まれるコンテンツのタイプを指定するだけで済みます。

dbgeng への DML コンテンツの提供

出力制御フラグ DEBUG_OUTCTL_DML は、dbgeng メソッドによって生成されたテキストを DML コンテンツとして処理する必要があることを示します。 このフラグが指定されていない場合、テキストはプレーン テキスト コンテキストとして扱われます。 DEBUG_OUTCTL_DML は、次のメソッドで使用できます。

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

指定されたテキストは、有効な文字に関する DML 規則に従う必要があります。

すべての出力ルーチンが拡張され、新しい書式指定子 %[h|w]Y{t} が許可されました。 この形式指定子は引数として文字列ポインターを持ち、指定されたテキストがプレーン テキストであり、出力処理中に DML 形式に変換する必要があることを示します。 これにより、呼び出し元は、DML 形式自体に事前に変換しなくても、DML コンテンツにプレーン テキストを含める簡単な方法が提供されます。 h および w 修飾子は、%s と同様に ANSI または Unicode テキストを示します。

次の表は、%Y 書式指定子の使用方法をまとめたものです。

%Y{t}: 引用符で囲まれた文字列。 出力形式 (最初の引数) が DML の場合、テキストを DML に変換します。

%Y{T}: 引用符で囲まれた文字列。 出力形式に関係なく、常にテキストを DML に変換します。

%Y{s}: 引用符で囲まれていない文字列。 出力形式 (最初の引数) が DML の場合、テキストを DML に変換します。

%Y{S}: 引用符で囲まれていない文字列。 出力形式に関係なく、常にテキストを DML に変換します。

%Y{as}: ULONG64。 デバッガーでフォーマットされたポインター フィールドの上位 32 ビット部分を埋めるために、空の文字列または 9 文字のスペースを追加します。 余分なスペースは、上の 8 つのゼロと ' 文字を含む 9 個のスペースを出力します。

%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 を介して送信されます。 Which パラメータはどのような種類の通知が届くかを示し、Flags、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 フラグが設定され、2 つの通知が 1 つにまとめられます。 バッファーに格納されているテキストがない場合は、フラッシュのみの通知が送信されます。

次に示すように、インタレスト マスク フラグは 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 コンテンツの両方を処理できる場合は、両方を登録できることに注意してください。 コールバックの出力処理中に、エンジンは変換を減らす形式を選択するため、両方をサポートするとエンジンでの変換が減る可能性があります。 ただし、これは必須ではなく、1 つの形式のみをサポートすることが期待される動作モードです。

自動変換

dbgeng は、必要に応じてプレーン テキストと DML の間で自動的に変換します。 たとえば、呼び出し元が DML コンテンツをエンジンに送信すると、エンジンはプレーン テキストのみを受け入れるすべての出力クライアントに対して、それをプレーン テキストに変換します。 あるいは、エンジンは、DML のみを受け入れるすべての出力コールバックについて、プレーン テキストを DML に変換します。

関連項目

デバッガー マークアップ言語の使用