DbgShell

Ein PowerShell-Frontend für die Windows-Debugger-Engine.

Bereit, sich per Tab durch die Glorie zu navigieren? Für eine schnellere Einführung werfen Sie einen Blick auf Getting Started.

Haftungsausschlüsse

1. Dieses Projekt wird nicht vom Windows-Debugger-Team erstellt, unterstützt oder überwacht. Das Debugger-Team freut sich über Feedback zu seiner API und den Frontends (windbg, kd usw.), hat jedoch keine Verbindung zu diesem Projekt. Reichen Sie keine Fehler oder Rückmeldungen zu diesem Projekt beim Debugger-Team ein.

2. Dies ist kein finanziertes Projekt: Es stehen keine offiziellen Ressourcen zur Verfügung, und es wird nur von Freiwilligen bearbeitet. Gehen Sie keine Produktionsabhängigkeit von diesem Projekt ein, es sei denn, Sie sind bereit, es vollständig selbst zu unterstützen. Sie können gerne Issues melden und Pull Requests einreichen, aber bedenken Sie, dass es aufgrund der begrenzten Freiwilligenressourcen eine Weile dauern kann, bis Ihre Einreichungen bearbeitet werden.

3. Dies ist ein experimentelles Projekt: Es ist nicht ausgereift, und Sie sollten mit häufigen bahnbrechenden Änderungen rechnen.

Konsequenz aus den obigen Haftungsausschlüssen: Ich würde davon abraten, DbgShell an live Ziele von hohem Wert anzuhängen.

Binärdateien

https://aka.ms/dbgshell-latest

Motivation

Haben Sie jemals versucht, etwas im Debugger zu automatisieren? (cdb/ntsd/kd/windbg) Wie ist das gelaufen?

Der Hauptantrieb für DbgShell ist, dass es einfach viel zu schwer ist, irgendetwas im Debugger zu automatisieren. Es gibt heute natürlich Einrichtungen, die bei der Automatisierung des Debuggers helfen. Aber meiner Meinung nach erfüllen sie die Bedürfnisse der Menschen nicht.

• Die Verwendung der integrierten Skriptsprache ist obskur, eingeschränkt, schwer richtig umzusetzen und schwer Hilfe zu bekommen.
• Das Schreiben einer vollwertigen Debugger-Erweiterungs-DLL ist sehr leistungsfähig, aber eine erhebliche Investition – viel zu teuer für die Lösung schneller, einmaliger Probleme beim Debuggen von zufälligen, realen Problemen. Trotz der Kosten gibt es eine große Anzahl von Debugger-Erweiterungen. Ich denke, es sollte nicht annähernd so viele geben; ich denke, der einzige Grund, warum es so viele gibt, ist, dass es keine brauchbaren Alternativen gibt.
• Bestehende Versuche, eine bessere Schnittstelle bereitzustellen (wie PowerDbg), basieren auf 'Scraping' und Textparsing, was enorm einschränkend ist (ganz zu schweigen von ideologisch ärgerlich) und daher nicht in der Lage ist, das Versprechen einer wirklich besseren Schnittstelle zu erfüllen (sie sind bestenfalls marginal besser).
• Bestehende Versuche, einen einfacheren Weg zum Schreiben einer Debugger-Erweiterung zu bieten, sind lediglich ein Notbehelf, der den Schmerz der Entwicklung einer Debugger-Erweiterung angeht; sie lösen nicht wirklich das größere Problem. (zwei Hauptmängel sind zum Beispiel: Sie sind immer noch zu niedrigstufig (man muss sich mit der dbgeng COM-API auseinandersetzen), und es gibt kein REPL)
• Das Debugger-Team hat kürzlich Javascript-Scripting eingeführt. Javascript ist eine viel bessere (und besser definierte) Sprache als die alte Windbg-Skriptsprache, aber ich denke, dass PowerShell einige Vorteile hat, der größte davon ist, dass niemand wirklich eine Javascript-Shell verwendet – PowerShell ist viel besser als kombinierte Shell- und Skriptsprache.

Das Ziel des DbgShell-Projekts ist es, die Vorzüge der objektbasierten PowerShell-Welt in die Debugging-Welt zu bringen. Wenn Sie 'dt' verwenden, um ein 'Objekt' auszugeben, sollten Sie ein tatsächliches Objekt erhalten. Scripting sollte so einfach sein wie das Schreiben eines PowerShell-Skripts.

Das DbgShell-Projekt bietet ein PowerShell-Frontend für dbgeng.dll, einschließlich:

• ein verwaltetes 'Objektmodell' (auf Wunsch auch von C# aus nutzbar), das eine höhere Abstraktionsebene als die dbgeng COM-API bietet,
• einen PowerShell-'Navigation Provider', der Aspekte eines Debugging-Ziels als hierarchischen Namespace darstellt (so können Sie 'cd' zu einem bestimmten Thread machen, 'dir' eingeben, um den Stack zu sehen, 'cd' in einen Frame, und nochmal 'dir' um Locals/Register usw. zu sehen),
• Cmdlets zur Manipulation des Ziels,
• einen benutzerdefinierten PowerShell-Host, der eine bessere Kontrolle über die Debugger-CLI-Erfahrung ermöglicht und Funktionen bereitstellt, die im standardmäßigen powershell.exe-Host nicht verfügbar sind (nämlich Unterstützung für Textfarben mittels ANSI-Escape-Sequenzen (à la ISO/IEC 6429))

Der benutzerdefinierte Host ist immer noch ein kommandozeilenbasiertes Programm (basierend auf conhost.exe) (analog zu ntsd/cdb/kd), kann aber von windbg aus aufgerufen werden (!DbgShell).

Neben der erheblichen Vereinfachung und Leistungssteigerung der Automatisierung wird es auch andere Anliegen angehen, wie die Benutzerfreundlichkeit für Personen, die die Debugger nicht so oft verwenden müssen. (eine Beschwerde, die ich gehört habe, ist: 'Wenn ich windbg verwenden muss, verbringe ich meine ganze Zeit in der .CHM')

Für erfahrene windbg-Benutzer ist ein weiteres Ziel, den Übergang so nahtlos wie möglich zu gestalten. So ist zum Beispiel der Namespace-Provider nicht der einzige Weg, auf Daten zuzugreifen; Sie können weiterhin traditionelle Befehle wie '~3 s', 'k' usw. verwenden.

Was meinen Sie mit "Automation" und "Scripting"?

Ich spreche nicht nur von der Art, wo man einen Texteditor öffnet und ein großes Skript schreibt, um etwas Komplexes zu tun – ich spreche auch davon, relativ einfache Dinge direkt auf der Kommandozeile aus dem Ärmel zu schütteln. Es gibt viele Situationen, in denen man ein bisschen Logik verwenden möchte, aber nichts so Großes oder Wiederverwendbares, dass man es speichern möchte. Es sollte einfach sein, 'Einzeiler' wie 'Halte bei CreateFile an, wenn die geöffnete Datei auf dem Desktop des Benutzers liegt und die Funktion Blah auf dem Stack ist', aus dem Handgelenk zu schütteln.

Warum PowerShell?

Lassen Sie mich klarstellen: Es hat ungefähr 4 Jahre gedauert, bis ich mich mit PowerShell 'angefreundet' habe. Ich finde, es hat Kanten, Aspekte, die einfach schwer sind, und viele Fehler, sowohl im Design als auch in der Implementierung. Manchmal nervt es mich wirklich. Trotzdem, die Vorteile von PowerShell sind überzeugend und haben mich davon überzeugt, dass es das Beste für dieses Projekt ist:

• Es ist sowohl eine Skriptumgebung als auch eine CLI-Umgebung. Die Tatsache, dass es beides tun muss, führt zu einigen negativen Dingen wie einer steileren Lernkurve, aber letztendlich ist es äußerst praktisch, weil Sie sowohl schnell Dinge in einem Kommandozeilen-REPL erledigen als auch vollwertige, robuste Skripte schreiben können.
• Es ist sehr auffindbar – Dinge wie Get-Command, Tab-Vervollständigung, die Fähigkeit, hierarchische Daten wie ein Dateisystem darzustellen, die Möglichkeiten zur Bereitstellung und Synthese von Hilfe, sind sehr gut.
• Tab-Vervollständigung. Ich weiß, ich habe es im vorherigen Punkt erwähnt, aber es ist toll genug für einen eigenen Punkt.
• Die Objekt-Pipeline: Die objektorientierte Natur der PowerShell-Pipeline ist so viel leistungsfähiger und einfacher zu bedienen als die schlechten alten Zeiten des string-parsing-basierten Scriptings, dass es nicht einmal lustig ist. Stellen Sie sich vor, Sie machen 'dt', um ein 'Objekt' auszugeben, und erhalten tatsächlich ein Objekt. DbgShell macht das.
• Die Leute kennen es: Ich schätze, dass die Anzahl der Personen, die PowerShell und/oder C# beherrschen, mindestens einige Größenordnungen größer ist als die Personen, die Windbg-Scripting-Techniken beherrschen. Das bedeutet, dass mehr Leute einen PowerShell-basierten Debugger leicht 'aufnehmen' können; und es bedeutet auch, dass der Pool potenzieller Helfer viel größer ist (für skriptbezogene Probleme jedenfalls).
• PowerShell ist immer noch eine Allzweck-Shell: Bei Verwendung von DbgShell haben Sie nicht nur Zugriff auf Debugger-Befehle, sondern Sie können 'cd' zum Dateisystem, zur Registrierung, zu AD usw. wechseln; Sie können Send-MailMessage, Get-WmiObject, Invoke-WebRequest, Invoke-RestMethod ausführen, beliebige Programme starten usw.

Aktueller Status

DbgShell befindet sich seit langer Zeit im 'Prototyping-Modus'. Ich habe viel Zeit damit verbracht, herauszufinden, wie etwas gemacht werden könnte oder sollte, aber nicht unbedingt alles 'fertiggestellt'. Es gibt eine riesige Anzahl von TODOs im aktuellen Code. Obwohl es also angefangen hat, tatsächlich nützlich zu werden, ist das Projekt noch ziemlich grün. Es kann jedoch genug demonstrieren, um Ihnen einen guten Eindruck davon zu vermitteln, wie es sein soll.

Unten sind einige Screenshots. Es ist wichtig zu beachten, dass nichts, was Sie sehen, dbgeng-Textausgabe ist. Obwohl einige Dinge in der Ausgabe vertraut aussehen, liegt das nur daran, dass ich PowerShells Formatierungs- und Ausgabefunktionen verwendet habe, um die Darstellung bestimmter Objekte anzupassen – die gesamte Ausgabe, die Sie sehen, entspricht tatsächlich echten, vollwertigen .NET-Objekten. Zum Beispiel entsprechen diese ModLoad-Nachrichten jeweils einem MS.Dbg.ModuleLoadedEventArgs-Objekt, das mehr Eigenschaften hat als das, was bei der Ausgabe an Out-Default angezeigt wird. Es gibt keinerlei String-Parsing von irgendetwas aus dbgeng. (Naja... fast. Ich habe ein paar Kompromisse gemacht, wo es keinen anderen Weg gibt, an Informationen zu kommen. Zum Beispiel Disassembly-Sachen oder das Parsen des symbolischen Namens einer Adjustor-Thunk-Funktion, um den Offset zu finden.)

Dies ist eine Art 'Hallo Welt'-Szenario: Anhängen an eine Instanz von cmd.exe. Ich verwende zuerst den PowerShell-eingebauten Befehl Start-Process, leite die Ausgabe dann an den DbgShell-Befehl Connect-Process weiter und stöbere dann im Namespace herum:

Hier habe ich mich an ein Testprogramm angehängt, den Stack angesehen, zu einem bestimmten Stack-Frame gewechselt, Locals ausgegeben, den Wert einer lokalen std::map inspiziert und einige Typinformationen für einen lokalen Enum-Wert untersucht. Beachten Sie die Anzeige des Enum-Werts: DbgShell behandelt nicht nur das Nachschlagen des symbolischen Namens für einzelne Enumeratoren, sondern auch, wenn mehrere Enumeratoren mit ODER verknüpft sind. Das können Sie auf dem Screenshot nicht erkennen, aber es gibt Tab-Vervollständigung für all diese Dinge.

Bemerkenswerte Funktionen

• Color: Unterstützung für Textfarben mittels ANSI-Escape-Sequenzen (à la ISO/IEC 6429)
• Custom formatting engine: Magst du .ps1xml-Zeug nicht? Ich auch nicht. Zusätzlich zu standardmäßigen Tabellen-, Listen- und benutzerdefinierten Ansichten können Sie 'Einzeilen'-Ansichten definieren, die sehr nützlich für die Anpassung von Symbolwertdarstellungen sind.
• Custom symbol value conversion: Für die meisten Variablen sind die Standardkonvertierung und -anzeige gut. Aber manchmal möchten Sie, dass der Debugger ein wenig mehr Arbeit für Sie erledigt. Die Symbolwert-Konvertierungsfunktion ermöglicht es beispielsweise, STL-Collection-Objekte in .NET-Collection-Objekte umzuwandeln, die viel einfacher zu handhaben sind.
• Derived type detection: Für den Fall, dass Ihre Variable ein IFoo ist, das eigentliche Objekt aber ein FooImpl.
• Rich type information: für Ihr programmtechnisches Vergnügen bereitgestellt.
• F: Funktioniert es in WinDbg? Ich werde nur WinDbg verwenden. A: Ja – laden Sie die Erweiterungs-DLL DbgShellExt.dll, und führen Sie dann '!dbgshell' aus, um eine DbgShell-Konsole zu öffnen.

Aktuelle Mängel

• Der größte Mangel derzeit ist, dass es den Kernel-Modus nicht gut unterstützt (wenn Sie sich bereits im richtigen Kontext befinden, können Sie Werte anzeigen, aber Sie können den Kontext nicht von DbgShell aus ändern, und der Namespace ist nicht verdrahtet).
• Obwohl Sie traditionelle Debugger-Erweiterungen auf die übliche Weise laden und ausführen können, fehlen noch viele windbg-Befehle.
• Remotes werden nicht unterstützt: Die dbgeng-API unterstützt das Verbinden mit einem Remote-Debugger. Leider sind die von der dbgeng-API bereitgestellten Symbol- und Typinformationen für die Anforderungen von DbgShell kritisch unzureichend, daher verwendet DbgShell die dbghelp-API. Leider gibt es so etwas wie Remote-dbghelp nicht. Wir werden mit dem Debugger-Team zusammenarbeiten müssen, um dieses Problem zu lösen.

Lizenz

Lizenziert unter der MIT-Lizenz.

Mitwirken

Dieses Projekt begrüßt Beiträge und Vorschläge. Die meisten Beiträge erfordern, dass Sie einer Contributor License Agreement (CLA) zustimmen, die besagt, dass Sie das Recht haben, uns die Rechte zur Nutzung Ihres Beitrags zu gewähren, und dies auch tun. Einzelheiten finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull-Request einreichen, wird ein CLA-Bot automatisch feststellen, ob Sie eine CLA bereitstellen müssen, und den PR entsprechend dekorieren (z. B. Label, Kommentar). Befolgen Sie einfach die Anweisungen des Bots. Sie müssen dies nur einmal für alle Repos tun, die unsere CLA verwenden.

Weitere Informationen zum Mitwirken am Projekt finden Sie unter Contributing.

Verhaltenskodex

Dieses Projekt hat den Microsoft Open Source Code of Conduct übernommen.

Weitere Informationen finden Sie in den Code of Conduct FAQ oder wenden Sie sich bei weiteren Fragen oder Kommentaren an [email protected].

Weitere Themen

• Getting Started with DbgShell

• Color

• Custom formatting engine

• Custom symbol value conversion

• Derived type detection

• Rich type information

• Hacking on DbgShell

• DbgEngWrapper

Sie finden eine kurze (3-minütige) Videoeinführung hier: https://youtu.be/ynbg2zZ1Igc