Menyesuaikan Output Debugger Menggunakan DML
Bahasa markup debugger (DML) menyediakan mekanisme untuk meningkatkan output dari debugger dan ekstensi. Mirip dengan HTML, dukungan markup debugger memungkinkan output untuk menyertakan direktif tampilan dan informasi non-tampilan tambahan dalam bentuk tag. Antarmuka pengguna debugger, seperti WinDbg mengurai informasi tambahan yang disediakan di DML untuk meningkatkan tampilan informasi dan memberikan perilaku baru, seperti tampilan kisi dan pengurutan. Topik ini menjelaskan bagaimana Anda dapat menyesuaikan output debug menggunakan DML. Untuk informasi umum tentang mengaktifkan dan menggunakan DML di debugger, lihat Menggunakan Debugger Markup Language.
DML tersedia di Windows 10 dan yang lebih baru.
Gambaran Umum DML
Pada DML manfaat utama itu untuk memberikan kemampuan untuk menautkan ke informasi terkait dalam output debugger. Salah satu tag DML utama adalah <tag tautan> yang memungkinkan produsen output menunjukkan bahwa informasi yang terkait dengan bagian output dapat diakses melalui tindakan tautan yang dinyatakan. Seperti halnya tautan HTML di browser web, ini memungkinkan pengguna untuk menavigasi informasi hyperlink.
Manfaat menyediakan konten hyperlink adalah dapat digunakan untuk meningkatkan kemampuan penemuan fungsionalitas ekstensi debugger dan debugger. Debugger dan ekstensinya berisi sejumlah besar fungsionalitas tetapi mungkin sulit untuk menentukan perintah yang sesuai untuk digunakan dalam skenario yang berbeda. Pengguna harus mengetahui perintah apa yang tersedia untuk digunakan dalam skenario tertentu. Perbedaan antara penelusuran kesalahan pengguna dan kernel menambah kompleksitas lebih lanjut. Ini sering berarti bahwa banyak pengguna tidak menyadari perintah debug yang dapat membantu mereka. Tautan DML menyediakan kemampuan untuk perintah debug arbitrer untuk dibungkus dalam presentasi alternatif, seperti teks deskriptif, sistem menu yang dapat diklik, atau bantuan tertaut. Dengan menggunakan DML, output perintah dapat ditingkatkan untuk memandu pengguna ke perintah terkait tambahan yang relevan untuk tugas yang ada.
Dukungan DML Debugger
- Jendela perintah di WinDbg mendukung semua perilaku DML dan akan menampilkan warna, gaya font, dan tautan.
- Debugger konsol – ntsd, cdb, dan kd – hanya mendukung atribut warna DML, dan satu-satunya saat berjalan di konsol sejati dengan mode warna diaktifkan.
- Debugger dengan I/O yang dialihkan, ntsd –d atau sesi remote.exe tidak akan menampilkan warna apa pun.
Spesifikasi Konten DML
DML tidak dimaksudkan untuk menjadi bahasa presentasi lengkap seperti HTML. DML sengaja sangat sederhana dan hanya memiliki beberapa tag.
Karena tidak semua alat debugger mendukung teks kaya, DML dirancang untuk memungkinkan terjemahan sederhana antara DML dan teks biasa. Ini memungkinkan DML berfungsi di semua alat debugger yang ada. Efek seperti warna dapat dengan mudah didukung karena menghapusnya tidak menghapus teks yang membawa informasi aktual.
DML bukan XML. DML tidak mencoba membawa informasi semantik atau terstruktur. Seperti disebutkan di atas, harus ada pemetaan sederhana antara DML dan teks biasa, karena alasan ini, tag DML semuanya dapat dibuang.
DML tidak dapat diperluas; semua tag telah ditentukan sebelumnya dan divalidasi untuk bekerja di semua alat debugger yang ada.
Struktur Tag
Mirip dengan XML, tag DML diberikan sebagai tagname awal <[args]> dan /tagname> berikut<.
Karakter Khusus
Konten DML kira-kira mengikuti aturan XML/HTML untuk karakter khusus. Karakter &, <, > dan " adalah khusus dan tidak dapat digunakan dalam teks biasa. Versi escape yang setara &, <, > dan ". Misalnya teks ini:
"Alice & Bob berpikir 3 < 4"
akan dikonversi ke DML berikut.
"Alice & Bob think 3 < 4"
Karakter pemformatan bahasa pemrograman C
Keberangkatan signifikan dari aturan XML/HTML adalah teks DML dapat menyertakan karakter pemformatan gaya aliran bahasa pemrograman C seperti \b, \t, \r dan \n. Ini untuk mendukung kompatibilitas dengan produksi dan konsumsi teks debugger yang ada.
Contoh DML
Misalkan file C:\Dml_Experiment.txt berisi baris berikut.
My DML Experiment
<link cmd="lmD musb*">List modules that begin with usb.</link>
Perintah berikut menampilkan teks dan tautan di jendela Browser Perintah.
.browse .dml_start c:\Dml_Experiment.txt
Jika Anda mengklik daftar modul yang dimulai dengan tautan usb , Anda akan melihat output yang mirip dengan gambar berikut.
Perilaku Klik Kanan di DML
Perilaku klik kanan tersedia di DML. Sampel ini menunjukkan cara menentukan perilaku klik kanan menggunakan <altlink> untuk mengirim perintah breakpoint bp (Set Breakpoint) dan mengirim u (Tidak Dirakit) dengan klik reguler.
<link cmd="u MyProgram!memcpy">
<altlink name="Set Breakpoint (bp)" cmd="bp MyProgram!memcpy" />
u MyProgram!memcpy
</link>
Referensi Tag DML
<Link>
<link [name="text"] [cmd="debugger_command"][alt="Hover text to display"] [section="name"]>link text</link>
Tag tautan adalah mekanisme penautan hiper dasar di DML. Ini mengarahkan antarmuka pengguna yang mendukung presentasi DML untuk menampilkan teks tautan sebagai tautan yang dapat diklik. Ketika tautan dengan spesifikasi cmd diklik perintah debugger dijalankan dan outputnya harus menggantikan output saat ini.
Argumen nama dan bagian memungkinkan navigasi antara tautan bernama, mirip dengan nama> HTML <dan dukungan #name. Ketika tautan yang memiliki argumen bagian diklik pada UI akan memindai tautan bernama dengan nama yang cocok dan akan menggulirnya ke dalam tampilan. Ini memungkinkan tautan untuk menunjuk ke bagian yang berbeda dari halaman yang sama (atau bagian tertentu dari halaman baru). Nama bagian DML terpisah untuk menghindari harus menentukan sintaks baru yang akan memungkinkan nama bagian di akhir string perintah.
Konversi ke teks biasa menghilangkan tag.
Contoh
<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>
Contoh
Contoh ini menunjukkan penggunaan atribut alt untuk membuat teks yang akan muncul saat Anda mengarahkan mouse ke atas tautan 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>
Tag <altlink> menyediakan perilaku klik kanan tersedia di DML. Ketika tautan dengan spesifikasi cmd diklik perintah debugger dijalankan dan outputnya harus menggantikan output saat ini. Tab <altlink> biasanya dipasangkan dengan <tag tautan> untuk mendukung perilaku klik reguler dan kanan.
Konversi ke teks biasa menghilangkan tag.
Contoh
Contoh ini menunjukkan cara menentukan perilaku klik kanan menggunakan <altlink> untuk mengirim perintah breakpoint bp (Set Breakpoint) dan mengirim u (Tidak Dirakit) dengan klik reguler.
<link cmd="u MyProgram!memcpy">
<altlink name="Set Breakpoint (bp)" cmd="bp MyProgram!memcpy" />
u MyProgram!memcpy
</link>
<Exec>
<exec cmd="debugger_command">teks deskriptif</exec>
Tag exec mirip dengan tag tautan karena teks deskriptif harus disajikan sebagai item yang dapat diklik. Namun, ketika tag exec digunakan di jendela browser perintah, perintah yang diberikan dijalankan tanpa mengganti output saat ini, tag ini menyediakan cara untuk menjalankan perintah dengan klik, dari menu.
Konversi ke teks biasa menghilangkan tag.
Contoh
Contoh ini menunjukkan cara menentukan dua perintah dengan klik reguler.
<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>tebal teks</b>
Tag ini meminta tebal. Yang <b>, <i> dan <u> dapat disarangkan untuk memiliki campuran properti.
Konversi ke teks biasa menghilangkan tag.
Contoh
Contoh ini menunjukkan cara menebalkan teks.
<b>This is bold Text</b>
<I>
<i>teks< miring/i>
Tag ini meminta miring. Yang <b>, <i> dan <u> dapat disarangkan untuk memiliki campuran properti.
Konversi ke teks biasa menghilangkan tag.
Contoh
Contoh ini menunjukkan cara memiringkan teks.
<i>This is italicized Text</i>
<U>
<u>teks< bergaris bawah/u>
Tag ini meminta teks bergaris bawah. Yang <b>, <i> dan <u> dapat disarangkan untuk memiliki campuran properti.
Konversi ke teks biasa menghilangkan tag.
Contoh
Contoh ini memperlihatkan cara menggaris bawahi teks.
<u>This is underlined Text</u>
Contoh
Contoh ini menunjukkan cara menggabungkan tag untuk menebalkan, menggaris bawahi, dan memiringkan teks.
<b><u><i>This is bold, underlined and italizized text. </i></u></b>
<Kolose>
<col fg="name" bg="name">text</col>
Minta warna latar depan dan latar belakang untuk teks. Warna diberikan sebagai nama warna yang diketahui alih-alih nilai absolut karena memungkinkan pelanggan untuk mengontrol jenis warna apa yang mereka lihat. Nama warna saat ini (default hanya berlaku untuk WinDbg).
Tag Elemen Latar Depan dan Latar Belakang
| Pengaturan | Deskripsi/ Contoh |
wbg - Latar belakang Windows wfg - Latar depan Windows |
Latar belakang jendela default dan warna latar depan. Default ke warna sistem untuk teks jendela dan jendela.
<col fg="wfg" bg="wbg"> Ini adalah latar depan standar / teks <latar belakang /col> |
clbg - Latar depan garis saat ini clfg - Latar belakang baris saat ini |
Latar belakang garis saat ini dan warna latar depan. Default ke warna sistem untuk sorotan dan sorot teks.
<col fg="clfg" bg="clbg"> Test Text - Current Line</col> |
empbg - Latar belakang yang ditekankan penekanan - Latar depan yang ditekankan |
Teks yang ditekankan. Default ke biru muda.
<col fg="empfg" bg="empbg"> Ini menekankan latar depan / teks <latar belakang /col> |
subbg - Latar belakang subdus subfg- Latar depan yang ditunda |
Teks yang disubduksi. Default ke warna sistem untuk teks caption tidak aktif dan keterangan tidak aktif.
<col fg="subfg" bg="subbg"> Ini adalah latar depan subdued / teks <latar belakang /col> |
normbg - Latar belakang normal normfg - Latar depan normal |
Normal <col fg="normfg" bg="normbg"> Test Text - Normal (normfg / normbg) </col> |
warnbg - Latar belakang peringatan warnfg - Latar depan peringatan |
Peringatan <col fg="warnfg" bg="warnbg"> Test Text - Warning (warnfg / warnbg) </col> |
errbg - Latar belakang kesalahan errfg - Latar depan kesalahan |
Kesalahan <col fg="errfg" bg="errbg"> Teks Uji - Kesalahan (errfg / errbg) </col> |
verbbg - Latar belakang Verbose verbfg - Latar depan Verbose |
Verbose <col fg="verbfg" bg="verbbg"> Test Text - Verbose (verbfg / verbbg) </col> |
Tag Elemen Tunggal Kode Sumber
srcnum - Konstanta numerik sumber |
Warna elemen sumber.
<col fg="srcnum" bg="wbg"> Test Text - srcnum </col> |
srcchar - Konstanta karakter sumber |
<col fg="srcchar" bg="wbg"> Test Text - srcchar </col> |
srcstr - Konstanta string sumber |
<col fg="srcstr" bg="wbg"> Test Text - srcstr </col> |
srcid -Pengidentifikasi sumber |
<col fg="srcid " bg="wbg"> Test Text - srcid </col> |
srckw- Kata kunci |
<col fg="srckw" bg="wbg"> Teks Uji - srckw </col> |
srcpair - Kurung kurawal sumber atau pasangan simbol yang cocok |
<col fg="srcpair" bg="empbbg"> Test Text - srcpair </col> |
srccmnt - Komentar sumber |
<col fg="srccmnt" bg="wbg"> Teks Uji - srccmnt </col> |
srcdrct - Arahan sumber |
<col fg="srcdrct" bg="wbg"> Test Text - srcdrct </col> |
srcspid - Pengidentifikasi khusus sumber |
<col fg="srcspid" bg="wbg"> Test Text - srcspid </col> |
srcannot - Anotasi sumber |
<col fg="srcannot" bg="wbg"> Test Text - srcannot </col> |
diubah - Data yang diubah |
Digunakan untuk data yang telah berubah sejak titik berhenti sebelumnya, seperti register yang diubah di WinDbg. Default ke merah.
<col fg="changed" bg="wbg"> Test Text - Changed</col> |
Kode Contoh DML
Contoh kode ini mengilustrasikan hal berikut.
- Memanggil perintah debug
- Menerapkan perintah klik kanan
- Menerapkan hover di atas teks
- Menggunakan warna dan teks kaya
<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
Contoh kode ini mengilustrasikan penggunaan tag warna dan pemformatan.
*** 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>
Penambahan DML ke Antarmuka dbgeng
API Mesin Debugger dan Ekstensi menyediakan antarmuka untuk menggunakan mesin debugger untuk membuat aplikasi kustom. Anda juga dapat menulis ekstensi kustom yang akan berjalan di WinDbg, KD, CDB, dan NTSD. Untuk informasi selengkapnya, lihat Menulis Ekstensi DbgEng. Bagian ini menjelaskan peningkatan DML yang tersedia untuk antarmuka mesin debugger.
Dbgeng sudah memiliki sekumpulan metode input penanganan teks dan antarmuka output, penggunaan DML hanya memerlukan spesifikasi jenis konten yang dibawa dalam teks input dan output.
Menyediakan Konten DML ke dbgeng
Bendera kontrol output DEBUG_OUTCTL_DML menunjukkan bahwa teks yang dihasilkan oleh metode dbgeng harus ditangani sebagai konten DML. Jika bendera ini tidak diberi teks diperlakukan sebagai konteks teks biasa. DEBUG_OUTCTL_DML dapat digunakan dengan metode berikut.
- IDebugControl4::ControlledOutput
- IDebugControl4::ControlledOutputVaList
- IDebugControl4::ControlledOutputWide
- IDebugControl4::ControlledOutputVaListWide
Teks yang diberikan harus mengikuti aturan DML untuk karakter yang valid.
Semua rutinitas output telah ditingkatkan untuk memperbolehkan penentu format baru %[h|w]Y{t}. Penentu format ini memiliki penunjuk string sebagai argumen dan menunjukkan bahwa teks yang diberikan adalah teks biasa dan harus dikonversi ke format DML selama pemrosesan output. Ini memberi pemanggil cara sederhana untuk menyertakan teks biasa dalam konten DML tanpa harus melakukan prakonversi ke format DML itu sendiri. Kualifikasi h dan w menunjukkan teks ANSI atau Unicode, seperti halnya %s.
Tabel berikut ini meringkas penggunaan penentu format %Y.
%Y{t}: String yang dikutip. Akan mengonversi teks ke DML jika format output (arg pertama) adalah DML.
%Y{T}: String yang dikutip. Akan selalu mengonversi teks ke DML terlepas dari format output.
%Y{s}: Untai (karakter) yang tidak dikutip. Akan mengonversi teks ke DML jika format output (arg pertama) adalah DML.
%Y{S}: Untai (karakter) yang tidak dikutip. Akan selalu mengonversi teks ke DML terlepas dari format output.
%Y{as}: ULONG64. Menambahkan string kosong atau 9 karakter penspasian untuk padding bagian tinggi 32-bit dari bidang penunjuk berformat debugger. Ruang ekstra menghasilkan 9 spasi yang mencakup 8 nol atas ditambah karakter '.
%Y{ps}: ULONG64. Ruang ekstra untuk bidang penunjuk berformat debugger padding (termasuk 8 nol atas ditambah karakter ' ).
%Y{l}: ULONG64. Alamat sebagai informasi baris sumber.
Cuplikan kode ini menggambarkan penggunaan penentu format %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;
}
Kode sampel ini akan menghasilkan output berikut.
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 <World>"
TEXT/NORMAL Y{s}: Hello <World>
TEXT/NORMAL Y{S}: Hello <World>
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]
Bendera kontrol tambahan, DEBUG_OUTCTL_AMBIENT_DML, memungkinkan spesifikasi teks konteks DML tanpa memodifikasi atribut kontrol output apa pun. DEBUG_OUTCTL_AMBIENT_TEXT telah ditambahkan juga sebagai alias yang lebih deskriptif untuk DEBUG_OUTCTL_AMBIENT yang ada sebelumnya. Bendera kontrol output ditentukan dalam 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
Menyediakan Konten DML Dari Debuggee
Dbgeng telah ditingkatkan untuk memindai output debuggee untuk penanda khusus - yang menunjukkan teks yang tersisa dalam sepotong output debuggee harus diperlakukan sebagai DML. Perubahan mode hanya berlaku untuk satu bagian output debuggee, seperti string OutputDebugString tunggal, dan bukan sakelar mode global.
Contoh ini menunjukkan campuran output biasa dan DML.
OutputDebugString(“This is plain text\n<?dml?>This is <col fg=\”emphfg\”>DML</col> text\n”);
Output yang dihasilkan, akan memiliki baris teks biasa diikuti oleh baris DML di mana Akronim DML ditampilkan dalam warna yang berbeda.
IDebugOutputCallbacks2
IDebugOutputCallbacks2 memungkinkan klien antarmuka dbgeng menerima konten DML penuh untuk presentasi. IDebugOutputCallbacks2 adalah ekstensi dari IDebugOutputCallbacks (bukan IDebugOutputCallbacksWide) sehingga dapat diteruskan ke metode SetOutputCallbacks yang ada. Mesin akan melakukan QueryInterface untuk IDebugOutputCallbacks2 untuk melihat antarmuka mana yang didukung objek panggilan balik output masuk. Jika objek mendukung IDebugOutputCallbacks2, semua output akan dikirim melalui metode IDebugOutputCallbacks2 yang diperluas; metode dasar IDebugOutputCallbacks::Output tidak akan digunakan.
Metode baru adalah:
IDebugOutputCallbacks2::GetInterestMask – Memungkinkan objek panggilan balik untuk menjelaskan jenis pemberitahuan output yang ingin diterimanya. Pilihan dasar adalah antara konten teks biasa (DEBUG_OUTCBI_TEXT) dan konten DML (DEBUG_OUTCBI_DML). Selain itu, objek panggilan balik juga dapat meminta pemberitahuan flush eksplisit (DEBUG_OUTCBI_EXPLICIT_FLUSH).
IDebugOutputCallbacks2::Output2 – Semua pemberitahuan IDebugOutputCallbacks2 datang melalui Output2. Parameter Mana yang menunjukkan jenis pemberitahuan apa yang masuk saat parameter Bendera, Arg, dan Teks membawa payload pemberitahuan. Pemberitahuan meliputi:
DEBUG_OUTCB_TEXT – Output teks biasa. Bendera berasal dari DEBUG_OUTCBF_*, Arg adalah masker output dan Teks adalah teks biasa. Ini hanya akan diterima jika DEBUG_OUTCBI_TEXT diberikan dalam masker bunga.
DEBUG_OUTCB_DML – Output konten DML. Bendera berasal dari DEBUG_OUTCBF_*, Arg adalah masker output dan Teks adalah konten DML. Ini hanya akan diterima jika DEBUG_OUTCBI_DML diberikan dalam masker bunga.
DEBUG_OUTCB_EXPLICIT_FLUSH – Penelepon telah memanggil FlushCallbacks tanpa teks yang di-buffer. Biasanya ketika teks buffer dibersihkan, bendera DEBUG_OUTCBF_COMBINED_EXPLICIT_FLUSH akan diatur, melipat dua pemberitahuan menjadi satu. Jika tidak ada teks yang di-buffer, pemberitahuan khusus flush akan dikirim.
Bendera masker bunga didefinisikan dalam dbgeng.h seperti yang ditunjukkan di sini.
// 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
Perhatikan bahwa objek output dapat mendaftar untuk teks dan konten DML jika dapat menangani keduanya. Selama pemrosesan output panggilan balik, mesin akan memilih format yang mengurangi konversi, sehingga mendukung keduanya dapat mengurangi konversi di mesin. Namun, tidak perlu, dan hanya mendukung satu format adalah mode operasi yang diharapkan.
Konversi Otomatis
Dbgeng akan secara otomatis mengonversi antara teks biasa dan DML seperlunya. Misalnya, jika penelepon mengirim konten DML ke mesin, mesin akan mengonversinya menjadi teks biasa untuk semua klien output yang hanya menerima teks biasa. Secara bergantian, mesin akan mengonversi teks biasa ke DML untuk semua panggilan balik output yang hanya menerima DML.
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk