Настройка выходных данных отладчика с помощью DML

Язык разметки отладчика (DML) предоставляет механизм для улучшения выходных данных отладчика и расширений. Как и в СЛУЧАЕ с HTML, поддержка разметки отладчика позволяет выводить директивы отображения и дополнительную информацию, не отображаемую в виде тегов. Пользовательские интерфейсы отладчика, такие как WinDbg, анализируют дополнительную информацию, предоставленную в DML, для улучшения отображения информации и предоставления новых поведений, таких как отображение сетки и сортировка. В этом разделе описывается, как настроить выходные данные отладки с помощью DML. Общие сведения о включении и использовании DML в отладчиках см. в разделе Использование языка разметки отладчика.

DML доступен в Windows 10 и более поздних версиях.

Общие сведения о DML

Основными преимуществами DML является возможность связывания со связанной информацией в выходных данных отладчика. Одним из основных тегов DML является <тег ссылки> , который позволяет производителю выходных данных указать, что доступ к информации, связанной с частью выходных данных, можно получить через указанное действие ссылки. Как и в случае с HTML-ссылками в веб-браузере, это позволяет пользователю перемещаться по гиперссылкам.

Преимущество предоставления содержимого с гиперссылками заключается в том, что его можно использовать для улучшения возможностей обнаружения отладчика и расширения отладчика. Отладчик и его расширения содержат большой объем функциональных возможностей, но может быть трудно определить соответствующую команду для использования в разных сценариях. Пользователи должны просто знать, какие команды доступны для использования в конкретных сценариях. Различия между отладкой пользователя и ядра добавляют дополнительную сложность. Это часто означает, что многие пользователи не знают о командах отладки, которые могут им помочь. Ссылки DML позволяют упаковать произвольные команды отладки в альтернативные презентации, такие как описательный текст, системы меню с возможностью щелчка или связанная справка. С помощью DML выходные данные команды можно улучшить, чтобы предоставить пользователю дополнительные связанные команды, относящиеся к задаче.

Поддержка DML отладчика

• Командное окно в WinDbg поддерживает все поведение DML и отображает цвета, стили шрифтов и ссылки.
• Отладчики консоли — ntsd, cdb и kd — поддерживают только атрибуты цвета DML и только при запуске в истинной консоли с включенным цветовым режимом.
• Отладчики с перенаправленными сеансами ввода-вывода, ntsd –d или remote.exe не будут отображать цвета.

Спецификация содержимого DML

DML не предназначен для полноценного языка презентации, например HTML. DML намеренно очень прост и имеет только несколько тегов.

Так как не все средства отладчика поддерживают форматированный текст, DML предназначен для простого перевода между DML и обычным текстом. Это позволяет DML работать во всех существующих средствах отладчика. Такие эффекты, как цвета, можно легко поддерживать, так как их удаление не приводит к удалению текста, вмеся в текст, вмесящий в фактическую информацию.

DML не является XML. DML не пытается использовать семантические или структурированные сведения. Как упоминалось выше, должно быть простое сопоставление между DML и обычным текстом, поэтому все теги DML можно удалить.

DML не является расширяемым; все теги предварительно определены и проверены для работы во всех существующих средствах отладчика.

Структура тегов

Как и в XML, теги DML предоставляются в качестве начального <тега [args]> и следующего </tagname>.

Специальные символы

Содержимое DML примерно соответствует правилам XML/HTML для специальных символов. Символы & , <> и " являются специальными и не могут использоваться в обычном тексте. Эквивалентными экранируемыми версиями являются &, <, > и ". Например, следующий текст:

"Алиса & Боб думаю 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

Если щелкнуть ссылку Список модулей, которые начинаются с usb , вы увидите выходные данные, аналогичные приведенному на следующем рисунке.

Поведение щелчка правой кнопкой мыши в DML

В DML доступно поведение щелчка правой кнопкой мыши. В этом примере показано, как определить поведение щелчка правой кнопкой мыши с помощью <altlink> для отправки команды точки останова (Задать точку останова) и отправки 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="Наведение текста на отображение"] [section="name"]>link text</link>

Тег ссылки — это базовый механизм гиперсвязи в DML. Он направляет пользовательские интерфейсы, поддерживающие презентацию DML, на отображение текста ссылки в виде ссылки с поддержкой щелчка. При щелчке ссылки со спецификацией cmd выполняется команда отладчика, и ее выходные данные должны заменить текущие выходные данные.

Аргументы name и section позволяют переходить между именованными ссылками, аналогично имени> HTML <и поддержке #name. Если щелкнуть ссылку с аргументом раздела, пользовательский интерфейс просканирует ссылку с соответствующим именем и прокрутит ее в поле зрения. Это позволяет ссылкам указывать на разные разделы одной и той же страницы (или на определенный раздел новой страницы). Имя раздела 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> для отправки команды точки останова (Задать точку останова) и отправки 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>

<b>полужирным шрифтом/<b>

Этот тег запрашивает полужирный шрифт. B<>, <i> и <u> могут быть вложенными, чтобы иметь сочетание свойств.

Преобразование в обычный текст удаляет теги.

Пример

В этом примере показано, как выделить текст полужирным шрифтом.

<b>This is bold Text</b>

<Я>

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

Теги элементов переднего плана и фона

Параметр	Описание / Пример
wbg — фон Windows wfg — windows foreground	Цвета фона и переднего плана окна по умолчанию. По умолчанию используется системный цвет для окна и текста окна. <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 — приглученный фон subfg — подчиненный передний план	Приглученный текст. По умолчанию используется системный цвет для неактивных подпись текста и неактивных субтитров. <col fg="subfg" bg="subbg"> This is subdued foreground / background text </col>
normbg — обычный фон normfg — обычный передний план	Норм. <col fg="normfg" bg="normbg"> Test Text - Normal (normfg / normbg) </col>
warnbg — фон предупреждения warnfg — предупреждение переднего плана	Предупреждение <col fg="warnfg" bg="warnbg"> Test Text - Warning (warnfg / warnbg) </col>
errbg — фон ошибки errfg — передний план ошибки	Ошибка <col fg="errfg" bg="errbg"> Test Text - Error (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"> Test Text - srcpair </col>
srccmnt — комментарий источника	<col fg="srccmnt" bg="wbg"> Test Text - srccmnt </col>
srcdrct — директива source	<col fg="srcdrct" bg="wbg"> Test Text - srcdrct </col>
srcspid — специальный идентификатор источника	<col fg="srcspid" bg="wbg"> Test Text - srcspid </col>
srcannot — заметка к источнику	<col fg="srcannot" bg="wbg"> Test Text - srcannot </col>
changed — измененные данные	Используется для данных, которые изменились с момента предыдущей точки остановки, например для измененных регистров в WinDbg. По умолчанию используется красный цвет. <col fg="changed" bg="wbg"> Test Text - Changed</col>

Пример кода 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>

Дополнения DML к интерфейсу dbgeng

API обработчика отладчика и расширения предоставляют интерфейс для использования обработчика отладчика для создания пользовательских приложений. Вы также можете написать пользовательские расширения, которые будут выполняться в WinDbg, KD, CDB и NTSD. Дополнительные сведения см. в статье Написание расширений DbgEng. В этом разделе описываются доступные усовершенствования DML для интерфейсов обработчика отладчика.

Dbgeng уже имеет набор методов ввода и выходных интерфейсов обработки текста. Для использования DML требуется только спецификация типа содержимого, переносимого во входном и выходном тексте.

Предоставление содержимого DML в dbgeng

Флаг элемента управления выходными данными 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 обозначают текст ANSI или Юникод, как и в случае с %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. Подсистема выполнит запрос QueryInterface для IDebugOutputCallbacks2, чтобы узнать, какой интерфейс поддерживается объектом обратного вызова входящего вывода. Если объект поддерживает 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, сложив два уведомления в одно. Если текст не помещается в буфер, отправляется уведомление только о сбросе.

Флаги маски интереса определены в файле 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.

См. также

Использование языка разметки отладчика