DbgShell

Un front-end PowerShell per il motore di debug di Windows.

Pronto per tabulare verso la gloria? Per un'introduzione più rapida, dai un'occhiata a Primi passi.

Avvertenze

1. Questo progetto non è prodotto, approvato o monitorato dal team di debug di Windows. Mentre il team di debug accoglie con favore feedback sulla loro API e sui front-end (windbg, kd, et al.), non hanno alcuna connessione con questo progetto. Non segnalare bug o feedback al team di debug riguardanti questo progetto.

2. Questo non è un progetto finanziato: non ha risorse ufficiali allocate, e viene sviluppato solo da volontari. Non assumere alcuna dipendenza produttiva da questo progetto a meno che tu non sia disposto a supportarlo completamente da solo. Sentiti libero di segnalare problemi e inviare richieste di pull, ma tieni presente che con le risorse volontarie limitate, potrebbe passare del tempo prima che le tue segnalazioni vengano gestite.

3. Questo è un progetto sperimentale: non è completamente maturo, e ci si devono aspettare modifiche sostanziali spesso.

Corollario delle avvertenze sopra: eviterei di collegare DbgShell a target live di alto valore.

Binari

https://aka.ms/dbgshell-latest

Motivazione

Hai mai provato ad automatizzare qualcosa nel debugger? (cdb/ntsd/kd/windbg) Come è andata?

La principale motivazione per DbgShell è che è davvero troppo difficile automatizzare qualsiasi cosa nel debugger. Ci sono delle strutture oggi per assistere nell'automazione del debugger, ovviamente. Ma a mio parere non stanno soddisfacendo le esigenze delle persone.

• L'uso del linguaggio di scripting integrato è arcano, limitato, difficile da padroneggiare, e difficile da trovare aiuto.
• Scrivere una DLL di estensione del debugger completa è molto potente, ma è un investimento significativo—troppo costoso per risolvere rapidi problemi "una tantum" mentre si esegue il debug di problemi casuali del mondo reale. Nonostante il costo, esistono un gran numero di estensioni del debugger. Penso che non dovrebbero essercene così tante; credo che l'unica ragione per cui ce ne siano così tante è perché non ci sono alternative valide.
• I tentativi esistenti di fornire un'interfaccia migliore (come PowerDbg) si basano su "raschiatura" e parsing del testo, che è estremamente limitante (per non dire ideologicamente fastidioso) e quindi non sono in grado di soddisfare la promessa di un'interfaccia veramente migliore (sono al massimo marginalmente migliori).
• I tentativi esistenti di fornire un modo più semplice per scrivere un'estensione del debugger sono solo un tappabuchi che affronta il dolore di sviluppare un'estensione; non risolvono veramente il problema più grande. (ad esempio, due gravi carenze sono: sono ancora troppo di basso livello (devi gestire l'API COM di dbgeng), e non c'è REPL)
• Il team di debug ha recentemente introdotto lo scripting Javascript. Javascript è un linguaggio molto migliore (e più ben definito) del vecchio linguaggio di scripting di windbg, ma penso che PowerShell abbia alcuni vantaggi, il maggiore dei quali è che nessuno usa davvero una shell Javascript—PowerShell è molto meglio come shell combinata e linguaggio di scripting.

L'obiettivo del progetto DbgShell è portare la bontà del mondo PowerShell orientato agli oggetti nel mondo del debug. Quando fai 'dt' per scaricare un 'oggetto', dovresti ottenere un oggetto reale. Lo scripting dovrebbe essere facile come scrivere uno script PowerShell.

Il progetto DbgShell fornisce un front-end PowerShell per dbgeng.dll, includendo:

• un "modello a oggetti" gestito (usabile da C# se desiderato), che è di livello superiore rispetto all'API COM di dbgeng,
• un "provider di navigazione" PowerShell, che espone aspetti di un target di debug come namespace gerarchico (così puoi "cd" in un thread specifico, digitare "dir" per vedere lo stack, "cd" in un frame, fare un altro "dir" per vedere variabili locali/registri/ecc.),
• cmdlet per manipolare il target,
• un host PowerShell personalizzato che permette un miglior controllo dell'esperienza CLI del debugger, oltre a fornire funzionalità non disponibili nell'host standard powershell.exe (in particolare, supporto per la colorazione del testo usando codici di escape ANSI (come da ISO/IEC 6429))

L'host personalizzato è ancora un programma a riga di comando (basato su conhost.exe) (analogo a ntsd/cdb/kd), ma può essere invocato da windbg (!DbgShell).

Oltre a rendere l'automazione molto più semplice e potente, affronterà anche altre problematiche, come la facilità d'uso per le persone che non devono usare i debugger così spesso. (una lamentela che ho sentito è che "quando mi trovo a dover usare windbg, passo tutto il mio tempo nel .CHM")

Per gli utenti esperti di windbg, d'altra parte, un altro obiettivo è rendere la transizione il più fluida possibile. Quindi, ad esempio, il provider di namespace non è l'unico modo per accedere ai dati; puoi ancora usare comandi tradizionali come "~3 s", "k", ecc.

Cosa intendi per "automazione" e "scripting"?

Non sto solo parlando del tipo di cosa in cui apri un editor di testo e scrivi un grosso script per fare qualcosa di complesso—sto anche parlando della capacità di sfornare roba relativamente semplice direttamente sulla riga di comando. Ci sono molte situazioni in cui vorresti poter usare un po' di logica, ma nulla di così grande o riutilizzabile da volerlo persino salvare. Dovrebbe essere facile sfornare semplici "one-liner" come "interrompi su CreateFile se il file in apertura è sul desktop dell'utente e la funzione Blah è sullo stack."

Perché PowerShell?

Chiariamoci: mi ci sono voluti circa 4 anni per "scaldarmi" con PowerShell. Penso che abbia spigoli vivi, aspetti che sono semplicemente difficili, e molti bug, sia nella progettazione che nell'implementazione. A volte mi irrita molto. Tuttavia, i benefici di PowerShell sono convincenti, e mi hanno convinto che è la cosa migliore da usare per questo progetto:

• È sia un ambiente di scripting che un ambiente CLI. Il fatto che debba fare entrambe le cose porta ad alcuni aspetti negativi come una curva di apprendimento più ripida, ma alla fine è estremamente comodo, perché vuoi essere in grado sia di fare cose velocemente in un REPL a riga di comando, sia di scrivere script completi e robusti.
• È molto esplorabile—cose come Get-Command, completamento tramite tab, la capacità di esporre dati gerarchici come un filesystem, le strutture per fornire e sintetizzare aiuto, sono molto buone.
• Completamento tramite tab. So di averlo già menzionato nel punto precedente, ma è abbastanza fantastico da meritarsi un punto a sé stante.
• Il pipeline di oggetti: la natura orientata agli oggetti del pipeline di PowerShell è così tanto più potente e facile da usare rispetto ai vecchi giorni dello scripting basato su parsing di stringhe che non è nemmeno divertente. Immagina di fare "dt" per "scaricare" un "oggetto", e ottenere effettivamente un oggetto. DbgShell lo fa.
• Le persone lo conoscono: stimo che il numero di persone che conoscono PowerShell e/o C# sia almeno di alcuni ordini di grandezza maggiore rispetto a coloro che conoscono le tecniche di scripting di windbg. Ciò significa che più persone saranno in grado di "prendere" facilmente un debugger basato su PowerShell; e significa anche che quando le persone hanno bisogno di aiuto, il pool di potenziali aiutanti è molto più ampio (per problemi legati allo scripting, comunque).
• PowerShell è ancora una shell per scopi generali: quando usi DbgShell, hai accesso non solo a comandi del debugger, ma puoi fare "cd" verso il filesystem, il registro, AD, ecc.; puoi eseguire Send-MailMessage, Get-WmiObject, Invoke-WebRequest, Invoke-RestMethod, eseguire programmi arbitrari, ecc.

Stato Attuale

DbgShell è stato in "modalità prototipazione" per molto tempo. Ho passato molto tempo a capire come qualcosa potrebbe o dovrebbe essere fatto, ma non necessariamente "finendo" tutto. Ci sono un enorme numero di TODO nel codice attuale. Quindi anche se ha iniziato a diventare effettivamente utile, il progetto è ancora abbastanza acerbo. Tuttavia, può sicuramente dimostrare abbastanza da darti un buon assaggio di come dovrebbe essere.

Di seguito alcune schermate. È importante notare che nulla di ciò che vedi è output di testo di dbgeng. Anche se alcune cose nell'output sembreranno familiari, è solo perché ho usato le funzionalità di formattazione e output di PowerShell per personalizzare come vengono visualizzati certi oggetti—tutto l'output che vedi corrisponde effettivamente a veri e propri oggetti .NET completi. Ad esempio, quei messaggi ModLoad corrispondono ciascuno a un oggetto MS.Dbg.ModuleLoadedEventArgs, che ha più proprietà di quelle visualizzate quando vengono inviati a Out-Default. Non c'è alcun parsing di stringhe da dbgeng. (Beh... quasi. Ho fatto alcune concessioni dove non c'è altro modo per ottenere informazioni. Ad esempio, cose di disassemblaggio, o l'analisi del nome simbolico di una funzione di thunk adjustor per trovare l'offset.)

Questo è una sorta di scenario "hello world": collegamento a un'istanza di cmd.exe. Uso prima il comando PowerShell integrato Start-Process, quindi invio l'output al comando DbgShell Connect-Process, e poi giro intorno al namespace:

Qui mi sono collegato a un programma di test, e ho guardato lo stack, sono passato a un frame particolare dello stack, ho scaricato le variabili locali, ispezionato il valore di una std::map locale, e ispezionato alcune informazioni di tipo per un valore enum locale. Notare la visualizzazione del valore dell'enumerazione: non solo DbgShell gestisce la ricerca del nome simbolico per singoli enumerandi, ma anche quando più enumerandi sono ORed insieme. Non puoi dirlo dallo screenshot, ma c'è il completamento tramite tab per tutta questa roba.

Caratteristiche Notevoli

• Color: supporto per la colorazione del testo usando codici di escape ANSI (come da ISO/IEC 6429)
• Custom formatting engine: Non ti piacciono le cose .ps1xml? Neanche a me. Oltre alle viste standard tabella, elenco e personalizzate, puoi definire viste "su una riga" che sono molto comode per personalizzare la visualizzazione dei valori dei simboli.
• Custom symbol value conversion: Per la maggior parte delle variabili, la conversione e la visualizzazione predefinite sono buone. Ma a volte, vorresti che il debugger facesse un po' più di lavoro per te. La funzione di conversione del valore dei simboli consente, ad esempio, che gli oggetti di raccolta STL vengano trasformati in oggetti di raccolta .NET molto più facili da gestire.
• Derived type detection: Per quando la tua variabile è un IFoo, ma l'oggetto reale è un FooImpl.
• Rich type information: esposta per il tuo piacere programmatico.
• D: Funziona in WinDbg? Userò solo WinDbg. R: Sì—carica la DLL di estensione DbgShellExt.dll, e poi esegui "!dbgshell" per aprire una console DbgShell.

Carenze Attuali

• La carenza più grande attualmente è che non supporta bene la modalità kernel (se sei già nel contesto appropriato, puoi visualizzare valori, ma non puoi cambiare contesto da DbgShell, e il namespace non è collegato).
• Anche se puoi caricare ed eseguire estensioni di debug tradizionali nel modo usuale, ci sono ancora molti comandi windbg mancanti.
• I remoti non sono supportati: l'API dbgeng supporta la connessione a un debugger remoto. Sfortunatamente, le informazioni sui simboli e sui tipi esposte dall'API dbgeng sono criticamente insufficienti per le esigenze di DbgShell, quindi DbgShell utilizza l'API dbghelp. Sfortunatamente, non esiste una cosa come dbghelp remoto. Dovremo lavorare con il team di debug per risolvere questo problema.

Licenza

Concesso in licenza sotto la MIT License.

Contribuire

Questo progetto accoglie contributi e suggerimenti. La maggior parte dei contributi richiede che tu accetti un Contributor License Agreement (CLA) che dichiari che hai il diritto di concederci effettivamente i diritti per utilizzare il tuo contributo. Per dettagli, visita https://cla.microsoft.com.

Quando invii una pull request, un CLA-bot determinerà automaticamente se hai bisogno di fornire un CLA e decorerà la PR in modo appropriato (ad esempio, etichetta, commento). Segui semplicemente le istruzioni fornite dal bot. Dovrai farlo solo una volta per tutti i repository che utilizzano il nostro CLA.

Vedi Contributing per maggiori informazioni su come contribuire al progetto.

Codice di Condotta

Questo progetto ha adottato il Microsoft Open Source Code of Conduct.

Per maggiori informazioni, consulta il Code of Conduct FAQ o contatta [email protected] per ulteriori domande o commenti.

Altri argomenti

• Primi passi con DbgShell

• Color

• Custom formatting engine

• Custom symbol value conversion

• Derived type detection

• Rich type information

• Sviluppare DbgShell

• DbgEngWrapper

Puoi trovare una breve introduzione video (3 minuti) qui: https://youtu.be/ynbg2zZ1Igc