Personalizando a saída do depurador usando DML
A DML (linguagem de marcação do depurador) fornece um mecanismo para aprimorar a saída do depurador e das extensões. Semelhante ao HTML, o suporte à marcação do depurador permite que a saída inclua diretivas de exibição e informações extras de não exibição na forma de marcas. As interfaces do usuário do depurador, como o WinDbg, analisam as informações extras fornecidas no DML para aprimorar a exibição de informações e fornecer novos comportamentos, como exibições de grade e classificação. Este tópico descreve como você pode personalizar sua saída de depuração usando DML. Para obter informações gerais sobre como habilitar e usar o DML nos depuradores, consulte Usando a linguagem de marcação do depurador.
O DML está disponível em Windows 10 e posteriores.
Visão geral do DML
Sobre os principais benefícios do DML, ele oferece a capacidade de vincular a informações relacionadas na saída do depurador. Uma das marcas DML primárias é a marca de <link> que permite que um produtor de saída indique que as informações relacionadas a uma parte da saída podem ser acessadas por meio da ação declarada do link. Assim como acontece com links HTML em um navegador da Web, isso permite que o usuário navegue por informações hiperlinkadas.
Um benefício de fornecer conteúdo hiperlink é que ele pode ser usado para aprimorar a capacidade de descoberta da funcionalidade de extensão de depurador e depurador. O depurador e suas extensões contêm uma grande quantidade de funcionalidade, mas pode ser difícil determinar o comando apropriado a ser usado em cenários diferentes. Os usuários devem simplesmente saber quais comandos estão disponíveis para uso em cenários específicos. As diferenças entre a depuração de usuário e kernel adicionam mais complexidade. Isso geralmente significa que muitos usuários não estão cientes dos comandos de depuração que podem ajudá-los. Os links DML fornecem a capacidade de comandos de depuração arbitrários serem encapsulados em apresentações alternativas, como texto descritivo, sistemas de menu clicáveis ou ajuda vinculada. Usando DML, a saída do comando pode ser aprimorada para orientar o usuário para comandos relacionados adicionais relevantes para a tarefa em questão.
Suporte ao DML do depurador
- A janela de comando no WinDbg dá suporte a todo o comportamento DML e mostrará cores, estilos de fonte e links.
- Os depuradores de console – ntsd, cdb e kd – só dão suporte aos atributos de cor do DML e ao serem executados em um console verdadeiro com o modo de cor habilitado.
- Os depuradores com sessões de E/S redirecionadas, ntsd –d ou remote.exe não exibirão nenhuma cor.
Especificação de conteúdo DML
O DML não se destina a ser uma linguagem de apresentação completa, como HTML. DML é deliberadamente muito simples e tem apenas um punhado de marcas.
Como nem todas as ferramentas de depurador dão suporte a rich text, o DML foi projetado para permitir a conversão simples entre DML e texto sem formatação. Isso permite que o DML funcione em todas as ferramentas de depurador existentes. Efeitos como cores podem ser facilmente suportados, pois removê-los não remove o texto que carrega as informações reais.
DML não é XML. O DML não tenta transportar informações semânticas nem estruturadas. Conforme mencionado acima, deve haver um mapeamento simples entre DML e texto sem formatação, por esse motivo, as marcas DML são todas descartadas.
O DML não é extensível; todas as marcas são predefinidas e validadas para funcionar em todas as ferramentas de depurador existentes.
Estrutura de marcas
Semelhante ao XML, as marcas DML são fornecidas como um nome de marca inicial <[args]> e um /tagname> a seguir<.
Caracteres especiais
O conteúdo DML segue aproximadamente as regras XML/HTML para caracteres especiais. Os caracteres &, <e > " são especiais e não podem ser usados em texto sem formatação. As versões de escape equivalentes são &, <e > ". Por exemplo, este texto:
"Alice & Bob pensa 34 < "
seria convertido no DML a seguir.
"Alice & Bob think 3 < 4"
Caracteres de formatação da linguagem de programação C
Uma saída significativa das regras XML/HTML é que o texto DML pode incluir caracteres de formatação no estilo de fluxo da linguagem de programação C, como \b, \t, \r e \n. Isso é para dar suporte à compatibilidade com a produção e o consumo de texto do depurador existentes.
DML de exemplo
Suponha que o arquivo C:\Dml_Experiment.txt contenha as linhas a seguir.
My DML Experiment
<link cmd="lmD musb*">List modules that begin with usb.</link>
O comando a seguir exibe o texto e o link na janela Navegador de Comandos.
.browse .dml_start c:\Dml_Experiment.txt
Se você clicar nos módulos listar que começam com o link usb, verá uma saída semelhante à imagem a seguir.
Comportamento de clique com o botão direito do mouse no DML
O comportamento do clique com o botão direito do mouse está disponível no DML. Este exemplo mostra como definir o comportamento do clique com o botão direito do mouse usando <altlink> para enviar um comando bp de ponto de interrupção (Definir Ponto de Interrupção) e enviar o u (Desmontagem) com um clique regular.
<link cmd="u MyProgram!memcpy">
<altlink name="Set Breakpoint (bp)" cmd="bp MyProgram!memcpy" />
u MyProgram!memcpy
</link>
Referência de marca DML
<Link>
<link [name="text"] [cmd="debugger_command"][alt="Focalizar texto para exibir"] [section="name"]>link text</link>
A marca de link é o mecanismo básico de hiper-vinculação no DML. Ele direciona as interfaces do usuário que dão suporte à apresentação DML para exibir o texto do link como um link clicável. Quando um link com uma especificação de cmd é clicado, o comando de depurador é executado e sua saída deve substituir a saída atual.
Os argumentos de nome e seção permitem a navegação entre links nomeados, semelhantes ao html de <um nome> e #name suporte. Quando um link que tem um argumento de seção for clicado na interface do usuário, será verificado um link chamado com um nome correspondente e rolará para exibição. Isso permite que os links apontem para seções diferentes da mesma página (ou uma seção específica de uma nova página). O nome da seção do DML é separado para evitar a necessidade de definir uma nova sintaxe que permitiria um nome de seção no final da cadeia de caracteres de comando.
A conversão em texto sem formatação remove as marcas.
Exemplo
<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>
Exemplo
Este exemplo mostra o uso do atributo alt para criar texto que aparecerá quando você passar o mouse sobre o link 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>
A <marca altlink> fornece um comportamento de clique com o botão direito do mouse disponível no DML. Quando um link com uma especificação de cmd é clicado, o comando de depurador é executado e sua saída deve substituir a saída atual. A <guia altlink> normalmente é emparelhada com a marca de <link> para dar suporte ao comportamento de clique regular e com o botão direito do mouse.
A conversão em texto sem formatação remove as marcas.
Exemplo
Este exemplo mostra como definir o comportamento do clique com o botão direito do mouse usando <altlink> para enviar um comando bp de ponto de interrupção (Definir Ponto de Interrupção) e enviar o u (Desmontagem) com um clique regular.
<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>
Uma marca exec é semelhante a uma marca de link na qual o texto descritivo deve ser apresentado como um item clicável. No entanto, quando a marca exec é usada em uma janela do navegador de comandos, o comando fornecido é executado sem substituir a saída atual, essa marca fornece uma maneira de executar comandos com um clique, em um menu.
A conversão em texto sem formatação remove as marcas.
Exemplo
Este exemplo mostra como definir dois comandos com um clique regular.
<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>negrito text</b>
Essa marca solicita negrito. O <b>, <i> e <u> podem ser aninhados para ter uma combinação das propriedades.
A conversão em texto sem formatação remove as marcas.
Exemplo
Este exemplo mostra como negrito de texto.
<b>This is bold Text</b>
<Eu>
<i>texto< itálico/i>
Essa marca solicita itálico. O <b>, <i> e <u> podem ser aninhados para ter uma combinação das propriedades.
A conversão em texto sem formatação remove as marcas.
Exemplo
Este exemplo mostra como italicizar texto.
<i>This is italicized Text</i>
<U>
<u>texto sublinhado</u>
Essa marca solicita texto sublinhado. O <b>, <i> e <u> pode ser aninhado para ter uma combinação das propriedades.
A conversão em texto sem formatação descarta as marcas.
Exemplo
Este exemplo mostra como sublinhar texto.
<u>This is underlined Text</u>
Exemplo
Este exemplo mostra como combinar marcas em negrito, sublinhar e itálico de texto.
<b><u><i>This is bold, underlined and italizized text. </i></u></b>
<Col>
<col fg="name" bg="name">text</col>
Solicite cores de primeiro plano e de plano de fundo para o texto. As cores são fornecidas como nomes de cores conhecidas em vez de valores absolutos, pois isso permite que os clientes controlem que tipo de cor eles vêem. Nomes de cores atuais (os padrões se aplicam somente ao WinDbg).
Marcas de elemento de primeiro plano e de plano de fundo
| Configuração | Descrição / Exemplo |
wbg – tela de fundo do Windows wfg – primeiro plano do Windows |
Tela de fundo da janela padrão e cores de primeiro plano. Padrão para cores do sistema para texto de janela e janela.
<col fg="wfg" bg="wbg"> Este é o primeiro plano padrão /background text </col> |
clbg - Primeiro plano da linha atual clfg – Plano de fundo da linha atual |
Tela de fundo da linha atual e cores de primeiro plano. Padrão para cores do sistema para realçar e realçar texto.
<col fg="clfg" bg="clbg"> Texto de teste - Linha< atual/col> |
empbg – Plano de fundo enfatizado emphfg - Primeiro plano enfatizado |
Texto enfatizado. O padrão é azul claro.
<col fg="empfg" bg="empbg"> Isso é ênfase em primeiro plano /background text </col> |
subbg - Plano de fundo subjugado subfg - Primeiro plano subjugado |
Texto subjugado. O padrão é a cor do sistema para legendas inativas legenda texto e inativas.
<col fg="subfg" bg="subbg"> This is subdued foreground /background text </col> |
normbg - Plano de fundo normal normfg - Primeiro plano normal |
Normal <col fg="normfg" bg="normbg"> Test Text - Normal (normfg / normbg) </col> |
warnbg - Plano de fundo de aviso warnfg - Primeiro plano de aviso |
Aviso <col fg="warnfg" bg="warnbg"> Texto de teste - Aviso (warnfg /warnbg) </col> |
errbg - Plano de fundo do erro errfg – primeiro plano do erro |
Erro <col fg="errfg" bg="errbg"> Texto de teste - Erro (errfg / errbg) </col> |
verbbg - Plano de fundo detalhado verbfg - Primeiro plano detalhado |
Detalhado <col fg="verbfg" bg="verbbg"> Test Text - Verbose (verbfg / verbbg) </col> |
Marcas de elemento único do código-fonte
srcnum - Constante numérica de origem |
Cores do elemento de origem.
<col fg="srcnum" bg="wbg"> Texto de teste - srcnum </col> |
srcchar - Constante de caractere de origem |
<col fg="srcchar" bg="wbg"> Texto de teste - srcchar </col> |
srcstr - Constante de cadeia de caracteres de origem |
<col fg="srcstr" bg="wbg"> Texto de teste - srcstr </col> |
srcid -Identificador de origem |
<col fg="srcid " bg="wbg"> Texto de teste - srcid </col> |
srckw- Palavra-chave |
<col fg="srckw" bg="wbg"> Texto de teste - srckw </col> |
srcpair - Chave de origem ou par de símbolos correspondentes |
<col fg="srcpair" bg="empbbg"> Texto de teste - srcpair </col> |
srccmnt - Comentário de origem |
<col fg="srccmnt" bg="wbg"> Texto de teste - srccmnt </col> |
srcdrct - Diretiva source |
<col fg="srcdrct" bg="wbg"> Texto de teste - srcdrct </col> |
srcspid - Identificador especial de origem |
<col fg="srcspid" bg="wbg"> Texto de teste - srcspid </col> |
srcannot - Anotação de origem |
<col fg="srcannot" bg="wbg"> Test Text - srcannot </col> |
alterado – Dados alterados |
Usado para dados que foram alterados desde um ponto de parada anterior, como registros alterados no WinDbg. O padrão é vermelho.
<col fg="changed" bg="wbg"> Test Text - Changed</col> |
Código de exemplo DML
Este código de exemplo ilustra o seguinte.
- Chamando comandos de depuração
- Implementando comandos de clique com o botão direito do mouse
- Implementando passar o mouse sobre o texto
- Usando cores e rich text
<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
Este código de exemplo ilustra o uso de marcas de cor e formatação.
*** 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>
Adições de DML à interface dbgeng
As APIs de Mecanismo e Extensão do Depurador fornecem uma interface para usar o mecanismo do depurador para criar aplicativos personalizados. Você também pode escrever extensões personalizadas que serão executadas em WinDbg, KD, CDB e NTSD. Para obter mais informações, consulte Escrevendo extensões DbgEng. Esta seção descreve os aprimoramentos de DML disponíveis para as interfaces do mecanismo do depurador.
O dbgeng já tem um conjunto de métodos de entrada de tratamento de texto e interfaces de saída, o uso de DML requer apenas a especificação do tipo de conteúdo transportado no texto de entrada e saída.
Fornecendo conteúdo DML para dbgeng
O sinalizador de controle de saída DEBUG_OUTCTL_DML indica que o texto gerado por um método dbgeng deve ser tratado como conteúdo DML. Se esse sinalizador não for fornecido, o texto será tratado como contexto de texto sem formatação. DEBUG_OUTCTL_DML pode ser usado com os métodos a seguir.
- IDebugControl4::ControlledOutput
- IDebugControl4::ControlledOutputVaList
- IDebugControl4::ControlledOutputWide
- IDebugControl4::ControlledOutputVaListWide
O texto dado deve seguir as regras DML para caracteres válidos.
Todas as rotinas de saída foram aprimoradas para permitir um novo especificador de formato %[h|w]Y{t}. Esse especificador de formato tem um ponteiro de cadeia de caracteres como um argumento e indica que o texto fornecido é texto sem formatação e deve ser convertido em formato DML durante o processamento de saída. Isso fornece aos chamadores uma maneira simples de incluir texto sem formatação no conteúdo DML sem precisar converter previamente no formato DML por conta própria. Os qualificadores h e w indicam texto ANSI ou Unicode, como com %s.
A tabela a seguir resume o uso do especificador de formato %Y.
%Y{t}: cadeia de caracteres entre aspas. Converterá texto em DML se o formato de saída (primeiro arg) for DML.
%Y{T}: cadeia de caracteres entre aspas. Sempre converterá texto em DML, independentemente do formato de saída.
%Y{s}: cadeia de caracteres sem aspas. Converterá texto em DML se o formato de saída (primeiro arg) for DML.
%Y{S}: cadeia de caracteres sem aspas. Sempre converterá texto em DML, independentemente do formato de saída.
%Y{as}: ULONG64. Adiciona uma cadeia de caracteres vazia ou 9 caracteres de espaçamento para preencher a parte alta de 32 bits dos campos de ponteiro formatados do depurador. O espaço extra gera 9 espaços que incluem os 8 zeros superiores mais o caractere .
%Y{ps}: ULONG64. Espaço extra para preenchimento de campos de ponteiro formatados pelo depurador (inclui os 8 zeros superiores mais o caractere ').
%Y{l}: ULONG64. Endereço como informações de linha de origem.
Este snippet de código ilustra o uso do especificador de formato %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;
}
Esse código de exemplo geraria a saída a seguir.
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]
Um sinalizador de controle adicional, DEBUG_OUTCTL_AMBIENT_DML, permite a especificação do texto de contexto DML sem modificar nenhum atributo de controle de saída. DEBUG_OUTCTL_AMBIENT_TEXT foi adicionado também como um alias mais descritivo para o DEBUG_OUTCTL_AMBIENT existente anteriormente. Os sinalizadores de controle de saída são definidos em 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
Fornecendo conteúdo DML de um depurador
O dbgeng foi aprimorado para verificar a saída de depuração de um marcador especial – – que indica que o texto restante em uma parte da saída de depuração deve ser tratado como DML. A alteração de modo só se aplica a uma única parte da saída de depuração, como uma única cadeia de caracteres OutputDebugString, e não é uma opção de modo global.
Este exemplo mostra uma combinação de saída simples e DML.
OutputDebugString(“This is plain text\n<?dml?>This is <col fg=\”emphfg\”>DML</col> text\n”);
A saída produzida terá uma linha de texto sem formatação seguida por uma linha de DML em que o Acrônimo DML é exibido em uma cor diferente.
IDebugOutputCallbacks2
IDebugOutputCallbacks2 permite que os clientes da interface dbgeng recebam conteúdo DML completo para apresentação. IDebugOutputCallbacks2 é uma extensão de IDebugOutputCallbacks (não IDebugOutputCallbacksWide) para que possa ser passada para o método SetOutputCallbacks existente. O mecanismo fará um QueryInterface para IDebugOutputCallbacks2 para ver qual interface o objeto de retorno de chamada de saída de entrada dá suporte. Se o objeto der suporte a IDebugOutputCallbacks2, toda a saída será enviada por meio dos métodos IDebugOutputCallbacks2 estendidos; o método básico IDebugOutputCallbacks::Output não será usado.
Os novos métodos são:
IDebugOutputCallbacks2::GetInterestMask – permite que o objeto de retorno de chamada descreva quais tipos de notificações de saída deseja receber. A opção básica é entre conteúdo de texto sem formatação (DEBUG_OUTCBI_TEXT) e conteúdo DML (DEBUG_OUTCBI_DML). Além disso, o objeto de retorno de chamada também pode solicitar notificação de liberações explícitas (DEBUG_OUTCBI_EXPLICIT_FLUSH).
IDebugOutputCallbacks2::Output2 – todas as notificações IDebugOutputCallbacks2 vêm por meio de Output2. O parâmetro Qual indica que tipo de notificação está chegando enquanto os parâmetros Flags, Arg e Text carregam o conteúdo da notificação. As notificações incluem:
DEBUG_OUTCB_TEXT – saída de texto sem formatação. Os sinalizadores são de DEBUG_OUTCBF_*, Arg é a máscara de saída e Texto é o texto sem formatação. Isso só será recebido se DEBUG_OUTCBI_TEXT tiver sido dada na máscara de interesse.
DEBUG_OUTCB_DML – saída de conteúdo DML. Os sinalizadores são de DEBUG_OUTCBF_*, Arg é a máscara de saída e Text é o conteúdo DML. Isso só será recebido se DEBUG_OUTCBI_DML tiver sido dada na máscara de interesse.
DEBUG_OUTCB_EXPLICIT_FLUSH – um chamador chamou FlushCallbacks sem texto em buffer. Normalmente, quando o texto armazenado em buffer é liberado, o sinalizador DEBUG_OUTCBF_COMBINED_EXPLICIT_FLUSH será definido, dobrando as duas notificações em uma. Se nenhum texto for armazenado em buffer, uma notificação somente de liberação será enviada.
Os sinalizadores de máscara de interesse são definidos em dbgeng.h, conforme mostrado aqui.
// 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
Observe que um objeto de saída pode se registrar para conteúdo de texto e DML se puder lidar com ambos. Durante o processamento de saída do retorno de chamada, o mecanismo escolherá o formato que reduz as conversões, portanto, o suporte a ambos pode reduzir as conversões no mecanismo. No entanto, não é necessário e dar suporte a apenas um formato é o modo de operação esperado.
Conversões automáticas
O dbgeng será convertido automaticamente entre texto sem formatação e DML, conforme necessário. Por exemplo, se um chamador enviar conteúdo DML para o mecanismo, o mecanismo o converterá em texto sem formatação para todos os clientes de saída que aceitam apenas texto sem formatação. Como alternativa, o mecanismo converterá texto sem formatação em DML para todos os retornos de chamada de saída que aceitam apenas DML.