Personalizzazione dell'output del debugger tramite DML

Il linguaggio di markup del debugger (DML) fornisce un meccanismo per migliorare l'output dal debugger e dalle estensioni. Analogamente a HTML, il supporto di markup del debugger consente all'output di includere direttive di visualizzazione e informazioni non visualizzate aggiuntive sotto forma di tag. Le interfacce utente del debugger, ad esempio WinDbg, analizzano le informazioni aggiuntive fornite in DML per migliorare la visualizzazione delle informazioni e fornire nuovi comportamenti, ad esempio la visualizzazione della griglia e l'ordinamento. Questo argomento descrive come personalizzare l'output di debug usando DML. Per informazioni generali sull'abilitazione e l'uso di DML nei debugger, vedere Uso del linguaggio di markup del debugger.

DML è disponibile in Windows 10 e versioni successive.

Panoramica di DML

Sui vantaggi principali di DML, offre la possibilità di collegare informazioni correlate nell'output del debugger. Uno dei tag DML principali è il <tag di collegamento> che consente a un produttore di output di indicare che è possibile accedere alle informazioni correlate a un pezzo di output tramite l'azione dichiarata del collegamento. Come per i collegamenti HTML in un Web browser, ciò consente all'utente di esplorare le informazioni ipertestuali.

Un vantaggio per fornire contenuto ipertestuale è che può essere usato per migliorare la individuabilità delle funzionalità di estensione debugger e debugger. Il debugger e le relative estensioni contengono una grande quantità di funzionalità, ma può essere difficile determinare il comando appropriato da usare in scenari diversi. Gli utenti devono semplicemente sapere quali comandi sono disponibili per l'uso in scenari specifici. Le differenze tra l'utente e il debug del kernel aggiungono ulteriore complessità. Questo significa spesso che molti utenti non sono a conoscenza dei comandi di debug che potrebbero aiutarli. I collegamenti DML consentono di eseguire il wrapping di comandi di debug arbitrari in presentazioni alternative, ad esempio testo descrittivo, sistemi di menu selezionabili o guida collegata. Usando DML, l'output dei comandi può essere migliorato per guidare l'utente a comandi correlati aggiuntivi pertinenti per l'attività.

Supporto DML del debugger

• La finestra dei comandi in WinDbg supporta tutto il comportamento DML e mostrerà colori, stili di carattere e collegamenti.
• I debugger della console, ntsd, cdb e kd, supportano solo gli attributi di colore di DML e l'unico durante l'esecuzione in una vera console con modalità colore abilitata.
• I debugger con I/O reindirizzati, ntsd -d o remote.exe sessioni non visualizzeranno alcun colore.

Specifica del contenuto DML

DML non è destinato a essere un linguaggio di presentazione completo, ad esempio HTML. DML è deliberatamente molto semplice e ha solo una manciata di tag.

Poiché non tutti gli strumenti del debugger supportano il testo avanzato, DML è progettato per consentire la traduzione semplice tra DML e testo normale. Ciò consente a DML di funzionare in tutti gli strumenti del debugger esistenti. Gli effetti come i colori possono essere facilmente supportati perché la rimozione non rimuove il testo che trasporta le informazioni effettive.

DML non è XML. DML non tenta di portare informazioni semantiche né strutturate. Come accennato in precedenza, è necessario che sia presente un semplice mapping tra DML e testo normale, per questo motivo, i tag DML sono tutti eliminabili.

DML non è estendibile; tutti i tag sono pre-definiti e convalidati per il funzionamento in tutti gli strumenti del debugger esistenti.

Struttura tag

Analogamente a XML, i tag DML vengono assegnati come nome tag iniziale <[args]> e un nome /tag> seguente<.

Caratteri speciali

Il contenuto DML segue approssimativamente le regole XML/HTML per caratteri speciali. I caratteri &, <e > " sono speciali e non possono essere usati in testo normale. Le versioni di escape equivalenti sono &, <e > ". Ad esempio questo testo:

"Alice & Bob pensa 3 < 4"

verrà convertito nel DML seguente.

"Alice & Bob think 3 &lt 4"

Caratteri di formattazione del linguaggio di programmazione C

Una significativa partenza dalle regole XML/HTML è che il testo DML può includere caratteri di formattazione in stile flusso del linguaggio di programmazione C, ad esempio \b, \t, \r e \n. Si tratta di supportare la compatibilità con la produzione e il consumo di testo del debugger esistenti.

Esempio di DML

Si supponga che il file C:\Dml_Experiment.txt contenga le righe seguenti.

My DML Experiment
<link cmd="lmD musb*">List modules that begin with usb.</link>

Il comando seguente visualizza il testo e il collegamento nella finestra Del browser dei comandi.

.browse .dml_start c:\Dml_Experiment.txt

Se si fa clic sui moduli Elenco che iniziano con il collegamento USB, viene visualizzato l'output simile all'immagine seguente.

Fare clic con il pulsante destro del mouse sul comportamento in DML

Il comportamento di clic con il pulsante destro del mouse è disponibile in DML. Questo esempio illustra come definire il comportamento di clic con il pulsante destro del mouse usando <altlink> per inviare un comando bp (Set Breakpoint) e inviare l'u (Unassemble) con un clic normale.

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

Informazioni di riferimento sul tag DML

<Link>

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

Il tag di collegamento è il meccanismo di collegamento di base in DML. Indirizza le interfacce utente che supportano la presentazione DML per visualizzare il testo del collegamento come collegamento selezionabile. Quando viene eseguito un collegamento con una specifica cmd, viene eseguito il comando debugger e l'output deve sostituire l'output corrente.

Gli argomenti nome e sezione consentono la navigazione tra collegamenti denominati, simile al nome> e al supporto di #name HTML<. Quando un collegamento con un argomento di sezione viene fatto clic sull'interfaccia utente eseguirà l'analisi di un collegamento denominato con un nome corrispondente e lo scorrerà nella visualizzazione. In questo modo i collegamenti puntano a sezioni diverse della stessa pagina (o una sezione specifica di una nuova pagina). Il nome della sezione di DML è separato per evitare di dover definire una nuova sintassi che consenta un nome di sezione alla fine della stringa di comando.

La conversione in testo normale elimina i tag.

Esempio

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

Esempio

In questo esempio viene illustrato l'uso dell'attributo alt per creare testo visualizzato quando si passa il puntatore del mouse sul collegamento 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>

Il <tag altlink> fornisce il comportamento di clic con il pulsante destro del mouse è disponibile in DML. Quando viene eseguito un collegamento con una specifica cmd, viene eseguito il comando debugger e l'output deve sostituire l'output corrente. La <scheda altlink> viene normalmente associata al tag di collegamento> per supportare il comportamento normale e fare clic con il pulsante destro del <mouse.

La conversione in testo normale elimina i tag.

Esempio

In questo esempio viene illustrato come definire il comportamento di clic con il pulsante destro del mouse usando <altlink> per inviare un comando bp (Set Breakpoint) e inviare l'u (Unassemble) con un clic regolare.

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

<Exec>

<exec cmd="debugger_command">testo< descrittivo/exec>

Un tag exec è simile a un tag di collegamento in cui il testo descrittivo deve essere presentato come elemento selezionabile. Tuttavia, quando il tag exec viene usato in una finestra del browser dei comandi, il comando specificato viene eseguito senza sostituire l'output corrente, questo tag fornisce un modo per avere comandi eseguiti con un clic, da un menu.

La conversione in testo normale elimina i tag.

Esempio

In questo esempio viene illustrato come definire due comandi con un clic normale.

<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 grassetto testo</b>>

Questo tag richiede grassetto. B<>, <i> e <u> possono essere annidati per avere una combinazione delle proprietà.

La conversione in testo normale elimina i tag.

Esempio

In questo esempio viene illustrato come in grassetto il testo.

<b>This is bold Text</b>

<Ho>

<i corsivo testo</i>>

Questo tag richiede corsivo. B<>, <i> e <u> possono essere annidati per avere una combinazione delle proprietà.

La conversione in testo normale elimina i tag.

Esempio

In questo esempio viene illustrato come in corsivo il testo.

<i>This is italicized Text</i>

<U>

<u>testo< sottolineato/u>

Questo tag richiede testo sottolineato. >B<, <i> e <u> possono essere annidati per avere una combinazione delle proprietà.

La conversione in testo normale elimina i tag.

Esempio

In questo esempio viene illustrato come sottolineare il testo.

<u>This is underlined Text</u>

Esempio

In questo esempio viene illustrato come combinare tag in grassetto, sottolineato e corsivo.

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

<Colonnello>

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

Richiedere i colori di primo piano e di sfondo per il testo. I colori vengono assegnati come nomi di colori noti anziché valori assoluti, in quanto consentono ai clienti di controllare il tipo di colore che vedono. Nomi di colore correnti (le impostazioni predefinite si applicano solo a WinDbg).

Tag degli elementi in primo piano e di sfondo

Tag a elemento singolo del codice sorgente

Codice di esempio DML

Questo codice di esempio illustra quanto segue.

• Chiamata di comandi di debug
• Implementazione dei comandi di clic con il pulsante destro del mouse
• Implementazione del passaggio del mouse sul testo
• Uso del colore e del rtf

<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

Questo codice di esempio illustra l'uso di tag di colore e formattazione.

*** 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>

Aggiunte DML all'interfaccia dbgeng

Le API del motore e dell'estensione del debugger forniscono un'interfaccia per usare il motore del debugger per creare applicazioni personalizzate. È anche possibile scrivere estensioni personalizzate che verranno eseguite in WinDbg, KD, CDB e NTSD. Per altre informazioni, vedere Scrittura di estensioni DbgEng. Questa sezione descrive i miglioramenti DML disponibili per le interfacce del motore di debugger.

Il dbgeng dispone già di un set di metodi di input e interfacce di output per la gestione del testo, l'uso di DML richiede solo la specifica del tipo di contenuto trasportato in testo di input e output.

Fornitura di contenuto DML a dbgeng

Il flag di controllo di output DEBUG_OUTCTL_DML indica che il testo generato da un metodo dbgeng deve essere gestito come contenuto DML. Se questo flag non viene specificato, il testo viene considerato come contesto di testo normale. DEBUG_OUTCTL_DML possono essere usati con i metodi seguenti.

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

Il testo specificato deve seguire le regole DML per i caratteri validi.

Tutte le routine di output sono state migliorate per consentire un nuovo identificatore di formato %[h|w]Y{t}. Questo identificatore di formato ha un puntatore stringa come argomento e indica che il testo specificato è testo normale e deve essere convertito in formato DML durante l'elaborazione dell'output. In questo modo i chiamanti possono includere testo normale nel contenuto DML senza dover eseguire la pre-conversione in formato DML. I qualificatori h e w indicano testo ANSI o Unicode, come con %s.

Nella tabella seguente viene riepilogato l'utilizzo dell'identificatore di formato %Y.

%Y{t}: stringa tra virgolette. Convertirà il testo in DML se il formato di output (primo arg) è DML.

%Y{T}: stringa tra virgolette. Convertirà sempre il testo in DML indipendentemente dal formato di output.

%Y{s}: stringa non racchiusa tra virgolette. Convertirà il testo in DML se il formato di output (primo arg) è DML.

%Y{S}: stringa non racchiusa tra virgolette. Convertirà sempre il testo in DML indipendentemente dal formato di output.

%Y{as}: ULONG64. Aggiunge una stringa vuota o 9 caratteri di spaziatura per la spaziatura interna della parte alta a 32 bit dei campi del puntatore formattati del debugger. Lo spazio aggiuntivo restituisce 9 spazi che includono gli 8 zeri superiori più il carattere ' .

%Y{ps}: ULONG64. Spazio aggiuntivo per i campi puntatore formattati del debugger di riempimento (include gli 8 zeri superiori più il carattere ').

%Y{l}: ULONG64. Indirizzo come informazioni sulla riga di origine.

Questo frammento di codice illustra l'uso dell'identificatore di 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;

}

Questo codice di esempio genera l'output seguente.

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]

Un flag di controllo aggiuntivo, DEBUG_OUTCTL_AMBIENT_DML, consente la specifica del testo del contesto DML senza modificare gli attributi del controllo di output. DEBUG_OUTCTL_AMBIENT_TEXT è stato aggiunto anche come alias più descrittivo per il DEBUG_OUTCTL_AMBIENT esistente in precedenza. I flag di controllo di output sono definiti in 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

Specifica del contenuto DML da un oggetto Debuggee

Il dbgeng è stato migliorato per analizzare l'output del debug per un marcatore speciale, che indica che il testo rimanente in un output di debug deve essere considerato come DML. La modifica della modalità si applica solo a una singola parte dell'output di debug, ad esempio una singola stringa OutputDebugString e non è un'opzione di modalità globale.

Questo esempio mostra una combinazione di output normale e DML.

OutputDebugString(“This is plain text\n<?dml?>This is <col fg=\”emphfg\”>DML</col> text\n”);

L'output prodotto avrà una riga di testo normale seguita da una riga di DML in cui l'acronimo DML viene visualizzato in un colore diverso.

IDebugOutputCallbacks2

IDebugOutputCallbacks2 consente ai client dell'interfaccia dbgeng di ricevere il contenuto DML completo per la presentazione. IDebugOutputCallbacks2 è un'estensione di IDebugOutputCallbacks (non IDebugOutputCallbacksWide) in modo che possa essere passata al metodo SetOutputCallbacks esistente. Il motore eseguirà queryInterface per IDebugOutputCallbacks2 per vedere quale interfaccia supporta l'oggetto callback di output in ingresso. Se l'oggetto supporta IDebugOutputCallbacks2 tutti gli output verranno inviati tramite i metodi IDebugOutputCallbacks2 estesi; Il metodo IDebugOutputCallbacks::Output di base non verrà utilizzato.

I nuovi metodi sono:

• IDebugOutputCallbacks2::GetInterestMask: consente all'oggetto di callback di descrivere i tipi di notifiche di output da ricevere. La scelta di base è tra contenuto di testo normale (DEBUG_OUTCBI_TEXT) e contenuto DML (DEBUG_OUTCBI_DML). Inoltre, l'oggetto callback può anche richiedere la notifica di scaricamenti espliciti (DEBUG_OUTCBI_EXPLICIT_FLUSH).

• IDebugOutputCallbacks2::Output2 : tutte le notifiche IDebugOutputCallbacks2 vengono inviate tramite Output2. Il parametro Which indica il tipo di notifica in arrivo mentre i parametri Flag, Arg e Text contengono il payload della notifica. Le notifiche includono:

  • DEBUG_OUTCB_TEXT: output di testo normale. I flag provengono da DEBUG_OUTCBF_*, Arg è la maschera di output e Text è il testo normale. Questo valore verrà ricevuto solo se DEBUG_OUTCBI_TEXT è stato assegnato nella maschera di interesse.

  • DEBUG_OUTCB_DML : output del contenuto DML. I flag provengono da DEBUG_OUTCBF_*, Arg è la maschera di output e Text è il contenuto DML. Questo verrà ricevuto solo se DEBUG_OUTCBI_DML è stato assegnato nella maschera di interesse.

  • DEBUG_OUTCB_EXPLICIT_FLUSH: un chiamante ha chiamato FlushCallbacks senza testo memorizzato nel buffer. In genere, quando il testo memorizzato nel buffer viene scaricato, verrà impostato il flag di DEBUG_OUTCBF_COMBINED_EXPLICIT_FLUSH, piegando le due notifiche in una. Se non viene inviato alcun testo memorizzato nel buffer, viene inviata una notifica di sola scaricamento.

I flag di maschera di interesse sono definiti in dbgeng.h, come illustrato di seguito.

// 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

Si noti che un oggetto di output può registrarsi sia per il testo che per il contenuto DML, se può gestirli entrambi. Durante l'elaborazione dell'output del callback il motore sceglierà il formato che riduce le conversioni, supportando quindi entrambe le conversioni nel motore. Non è tuttavia necessario e il supporto di un solo formato è la modalità prevista dell'operazione.

Conversioni automatiche

Il dbgeng convertirà automaticamente tra testo normale e DML in base alle esigenze. Ad esempio, se un chiamante invia contenuto DML al motore, il motore lo convertirà in testo normale per tutti i client di output che accettano solo testo normale. In alternativa, il motore convertirà testo normale in DML per tutti i callback di output che accettano solo DML.

Vedere anche

Uso del linguaggio di markup del debugger