Verwenden von Visual Studio Code zum Debuggen kompilierter Cmdlets

2025-02-06

In diesem Handbuch wird gezeigt, wie Sie C#-Quellcode für ein kompiliertes PowerShell-Modul mithilfe von Visual Studio Code (VS Code) und der C#-Erweiterung interaktiv debuggen.

Es wird eine Vertrautheit mit dem Visual Studio Code-Debugger vorausgesetzt.

Eine allgemeine Einführung in den VS Code-Debugger finden Sie unter Debuggen in Visual Studio Code.
Beispiele für das Debuggen von PowerShell-Skriptdateien und -modulen finden Sie unter Verwendung von Visual Studio Code zur Remote-Bearbeitung und zum Debugging.

In diesem Handbuch wird davon ausgegangen, dass Sie die Anweisungen im handbuch Writing Portable Modules gelesen und befolgt haben.

Erstellen eines Buildtasks

Erstellen Sie Ihr Projekt automatisch, bevor Sie eine Debugsitzung starten. Durch die Neuerstellung wird sichergestellt, dass Sie die neueste Version des Codes debuggen.

Konfigurieren einer Buildaufgabe:

Führen Sie in der Befehlspaletteden Befehl "Standardbuildaufgabe konfigurieren" aus.

Ausführen von „Configure Default Build Task“
Wählen Sie im Dialogfeld Select a task to configure (Task zum Konfigurieren auswählen) Create tasks.json file from template (tasks.json-Datei aus einer Vorlage erstellen) aus.
Wählen Sie im Dialogfeld Select a Task Template (Taskvorlage auswählen) .NET Core aus.

Wenn noch keine datei vorhanden ist, wird eine neue tasks.json datei erstellt.

So testen Sie die Erstellungsaufgabe:

Führen Sie in der Befehlspaletteden Befehl "Run Build Task" aus.
Wählen Sie im Dialogfeld Select the build task to run (Auszuführenden Buildtask auswählen) build (Erstellen) aus.

Informationen zu gesperrten DLL-Dateien

Standardmäßig zeigt ein erfolgreicher Build keine Ausgabe im Terminalbereich an. Wenn Sie eine Ausgabe sehen, die den Text Project file doesn't exist (Es ist keine Projektdatei vorhanden), sollten Sie die tasks.json-Datei bearbeiten. Fügen Sie den expliziten Pfad zum C#-Projekt ein, das als "${workspaceFolder}/myModule"ausgedrückt wird. In diesem Beispiel ist myModule der Name des Projektordners. Dieser Eintrag muss nach dem Eintrag build in der Liste args wie folgt eingefügt werden:

    {
        "label": "build",
        "command": "dotnet",
        "type": "shell",
        "args": [
            "build",
            "${workspaceFolder}/myModule",
            // Ask dotnet build to generate full paths for file names.
            "/property:GenerateFullPaths=true",
            // Do not generate summary otherwise it leads to duplicate errors in Problems panel
            "/consoleloggerparameters:NoSummary",
        ],
        "group": "build",
        "presentation": {
            "reveal": "silent"
        },
        "problemMatcher": "$msCompile"
    }

Beim Debuggen wird die Modul-DLL in die PowerShell-Sitzung im VS Code-Terminal importiert. Die DLL wird gesperrt. Die folgende Meldung wird angezeigt, wenn Sie die Buildaufgabe ausführen, ohne die Terminalsitzung zu schließen:

Could not copy "obj\Debug\netstandard2.0\myModule.dll" to "bin\Debug\netstandard2.0\myModule.dll"`.

Terminalsitzungen müssen geschlossen werden, bevor Sie Neuerstellungen durchführen.

Einrichten des Debuggers

Zum Debuggen des PowerShell-Cmdlets müssen Sie eine benutzerdefinierte Startkonfiguration einrichten. Diese Konfiguration wird für Folgendes verwendet:

Erstellen des Quellcodes
Starten Sie PowerShell mit Ihrem geladenem Modul
Lassen Sie PowerShell im Terminalbereich geöffnet

Wenn Sie ihr Cmdlet in der Terminalsitzung aufrufen, stoppt der Debugger an allen Haltepunkten, die in Ihrem Quellcode festgelegt sind.

Konfigurieren von launch.json für PowerShell

Installieren der C#-Erweiterung für Visual Studio Code
Fügen Sie im Debugbereich eine Debugkonfiguration hinzu.
Wählen Sie im Dialogfeld Select environment.NET Core aus
Die launch.json Datei wird im Editor geöffnet. Wenn sich der Cursor innerhalb des configurations-Arrays befindet, sehen Sie das configuration-Auswahlelement. Wenn diese Liste nicht angezeigt wird, wählen Sie Add Configuration (Konfiguration hinzufügen) aus.
Um eine Standarddebugkonfiguration zu erstellen, wählen Sie Starten der .NET Core Console Appaus:

.NET Core Console App starten

Bearbeiten Sie die Felder name, program, argsund console wie folgt:

 {
     "name": "PowerShell cmdlets: pwsh",
     "type": "coreclr",
     "request": "launch",
     "preLaunchTask": "build",
     "program": "pwsh",
     "args": [
         "-NoExit",
         "-NoProfile",
         "-Command",
         "Import-Module ${workspaceFolder}/myModule/bin/Debug/netstandard2.0/myModule.dll",
     ],
     "cwd": "${workspaceFolder}",
     "stopAtEntry": false,
     "console": "integratedTerminal"
 }

Das feld program wird verwendet, um pwsh zu starten, sodass das zu debuggende Cmdlet ausgeführt werden kann. Das argument -NoExit verhindert, dass die PowerShell-Sitzung beendet wird, sobald das Modul importiert wird. Der Pfad im Import-Module-Argument ist der Build-Standardausgabepfad, wenn Sie den Leitfaden Schreiben von portablen Modulen befolgt haben. Wenn Sie ein Modulmanifest (.psd1 Datei) erstellt haben, sollten Sie stattdessen den Pfad zu dieser Datei verwenden. Das / Pfadtrennzeichen funktioniert unter Windows, Linux und macOS. Sie müssen das integrierte Terminal verwenden, um die PowerShell-Befehle auszuführen, die Sie debuggen möchten.

Anmerkung

Wenn der Debugger an Haltepunkten nicht angehalten wird, suchen Sie in der Visual Studio Code Debug-Konsole nach einer Zeile, die enthält:

Loaded '/path/to/myModule.dll'. Skipped loading symbols. Module is optimized and the debugger option 'Just My Code' is enabled.

Wenn dies angezeigt wird, fügen Sie ihrer Startkonfiguration "justMyCode": false hinzu (auf der gleichen Ebene wie "console": "integratedTerminal".

Konfigurieren von launch.json für Windows PowerShell

Diese Startkonfiguration funktioniert zum Testen Ihrer Cmdlets in Windows PowerShell (powershell.exe). Erstellen Sie eine zweite Startkonfiguration mit den folgenden Änderungen:

name sollte PowerShell cmdlets: powershell lauten.
type sollte clr lauten.

program sollte powershell lauten.

Es sollte wie folgt aussehen:

 {
     "name": "PowerShell cmdlets: powershell",
     "type": "clr",
     "request": "launch",
     "preLaunchTask": "build",
     "program": "powershell",
     "args": [
         "-NoExit",
         "-NoProfile",
         "-Command",
         "Import-Module ${workspaceFolder}/myModule/bin/Debug/netstandard2.0/myModule.dll",
     ],
     "cwd": "${workspaceFolder}",
     "stopAtEntry": false,
     "console": "integratedTerminal"
 }

Starten einer Debugsitzung

Jetzt ist alles bereit, mit dem Debuggen zu beginnen.

Platzieren Sie einen Haltepunkt im Quellcode für das Cmdlet, das Sie debuggen möchten:

Ein Haltepunkt wird als roter Punkt am Seitenrand angezeigt
Achten Sie darauf, dass die relevante Konfiguration für PowerShell-Cmdlets im Konfigurations-Dropdownmenü in der Debug-Ansicht ausgewählt ist:

Wählen Sie die Startkonfiguration
Drücken Sie F5-, oder klicken Sie auf die Schaltfläche Debuggen starten
Wechseln Sie zum Terminalbereich, und rufen Sie Ihr Cmdlet auf:

Aufrufen des Cmdlets
Die Ausführung wird am Haltepunkt angehalten:

Die Ausführung hält am Haltepunkt an

Sie können den Quellcode durchlaufen, Variablen prüfen und den Aufrufstapel überprüfen.

Wenn Sie das Debuggen beenden möchten, klicken Sie in der Symbolleiste „Debuggen“ auf Stop, oder drücken Sie UMSCHALT+F5. Die Shell, die zum Debuggen verwendet wird, beendet und gibt die Sperre in der kompilierten DLL-Datei frei.

Freigeben über