DML을 사용하여 디버거 출력 사용자 지정

DML(디버거 태그 언어)은 디버거 및 확장의 출력을 향상시키기 위한 메커니즘을 제공합니다. HTML과 마찬가지로 디버거의 태그 지원을 사용하면 출력에 표시 지시문과 추가 비표시 정보가 태그 형식으로 포함될 수 있습니다. WinDbg와 같은 디버거 사용자 인터페이스는 DML에 제공된 추가 정보를 구문 분석하여 정보 표시를 향상시키고 그리드 표시 및 정렬과 같은 새로운 동작을 제공합니다. 이 항목에서는 DML을 사용하여 디버그 출력을 사용자 지정하는 방법을 설명합니다. 디버거에서 DML을 사용하도록 설정하고 사용하는 방법에 대한 일반적인 내용은 디버거 태그 언어 사용을 참조하세요.

DML은 Windows 10 이상에서 사용할 수 있습니다.

DML 개요

DML의 주요 이점 중에서 디버거 출력의 관련 정보에 연결할 수 있는 기능을 제공합니다. 기본 DML 태그 중 하나는 출력 생산자가 링크>의 명시된 작업을 통해 출력 부분과 관련된 정보에 액세스할 수 있음을 나타낼 수 있는 링크 태그<입니다. 웹 브라우저의 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 태그는 시작 <태그 이름 [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로 시작하는 모듈 나열 링크를 클릭하면 다음 이미지와 유사한 출력이 표시됩니다.

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 [name="text"] [cmd="debugger_command"][alt="표시할 텍스트 가리키기"] [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(중단점 설정) 명령을 보내고 정기적으로 클릭하여 u(언어셈블)를 보내는 방법을 보여 줍니다.

<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 전경	기본 창 배경 및 전경색입니다. 창 및 창 텍스트의 시스템 색은 기본적으로 설정됩니다. <col fg="wfg" bg="wbg"> 표준 전경/배경 텍스트 </col입니다.>
clbg - 현재 선 전경 clfg - 현재 선 배경	현재 선 배경 및 전경색. 강조 표시 및 강조 텍스트에 대한 시스템 색의 기본값입니다. <col fg="clfg" bg="clbg"> 테스트 텍스트 - 현재 줄</col>
empbg - 강조된 배경 emphfg - 전경이 강조됨	강조된 텍스트입니다. 기본값은 연한 파란색입니다. <col fg="empfg" bg="empbg"> 이것은 전경/배경 텍스트 </col에 중점을 둡니다.>
subbg - 차분한 배경 subfg- 차분한 전경	차분 텍스트입니다. 비활성 캡션 텍스트 및 비활성 캡션의 경우 기본적으로 시스템 색으로 설정됩니다. <col fg="subfg" bg="subbg"> 이것은 차분한 전경/배경 텍스트 </col입니다.>
normbg - 기본 배경 normfg - 일반 전경	보통 <col fg="normfg" bg="normbg"> Test Text - Normal (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 -Source 식별자	<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"> 테스트 텍스트 - 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>
변경됨 - 변경된 데이터	WinDbg의 변경된 레지스터와 같이 이전 중지점 이후 변경된 데이터에 사용됩니다. 기본값은 빨간색입니다. <col fg="changed" bg="wbg"> 테스트 텍스트 - 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>

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 또는 유니코드 텍스트를 나타냅니다.

다음 표에는 %Y 형식 지정자의 사용이 요약되어 있습니다.

%Y{t}: 따옴표 붙은 문자열입니다. 출력 형식(첫 번째 arg)이 DML인 경우 텍스트를 DML로 변환합니다.

%Y{T}: 따옴표 붙은 문자열입니다. 출력 형식에 관계없이 항상 텍스트를 DML로 변환합니다.

%Y{s}: 따옴표가 지정되지 않은 문자열입니다. 출력 형식(첫 번째 arg)이 DML인 경우 텍스트를 DML로 변환합니다.

%Y{S}: 따옴표가 지정되지 않은 문자열입니다. 출력 형식에 관계없이 항상 텍스트를 DML로 변환합니다.

%Y{as}: ULONG64. 디버거 형식 포인터 필드의 높은 32비트 부분을 패딩하기 위한 빈 문자열 또는 9자 간격을 추가합니다. 추가 공간은 위쪽 80과 ' 문자를 포함하는 9개의 공백을 출력합니다.

%Y{ps}: ULONG64. 디버거 형식의 포인터 필드를 패딩하기 위한 추가 공간입니다(8개 0 위와 ' 문자 포함).

%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 콘텐츠 제공

디버그 출력의 나머지 텍스트를 DML로 처리해야 했음을 나타내는 특수 마커에 대한 디버그기 출력을 검사하도록 dbgeng가 향상되었습니다. 모드 변경은 단일 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는 기존 SetOutputCallbacks 메서드에 전달할 수 있도록 IDebugOutputCallbacks(IDebugOutputCallbacksWide 아님)의 확장입니다. 엔진은 IDebugOutputCallbacks2에 대한 QueryInterface를 수행하여 들어오는 출력 콜백 개체가 지원하는 인터페이스를 확인합니다. 개체가 IDebugOutputCallbacks2를 지원하는 경우 모든 출력은 확장된 IDebugOutputCallbacks2 메서드를 통해 전송됩니다. 기본 IDebugOutputCallbacks::Output 메서드는 사용되지 않습니다.

새 메서드는 다음과 같습니다.

• IDebugOutputCallbacks2::GetInterestMask – 콜백 개체가 수신하려는 출력 알림의 종류를 설명할 수 있도록 허용합니다. 기본 선택은 일반 텍스트 콘텐츠(DEBUG_OUTCBI_TEXT)와 DML 콘텐츠(DEBUG_OUTCBI_DML) 중에서 선택할 수 있습니다. 또한 콜백 개체는 명시적 플러시(DEBUG_OUTCBI_EXPLICIT_FLUSH)에 대한 알림을 요청할 수도 있습니다.

• IDebugOutputCallbacks2::Output2 – 모든 IDebugOutputCallbacks2 알림은 Output2를 통해 제공됩니다. What 매개 변수는 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로 변환합니다.

참고 항목

디버거 태그 언어 사용