Debugging Tools in VS Code¶

Visual Studio Code provides a rich, integrated debugging experience for PowerShell. These tools help you inspect variables, step through code, set breakpoints, and understand exactly what your script is doing at runtime. Mastering the VS Code debugger is essential for diagnosing logic errors, unexpected behavior, and complex control‑flow issues.

1. Requirements¶

To debug PowerShell scripts in VS Code, you need:

• VS Code
• PowerShell extension (official Microsoft extension)
• PowerShell 7+ or Windows PowerShell

Once the extension is installed, VS Code automatically enables debugging features for .ps1 files.

2. Running a Script in the Debugger¶

Open any .ps1 file and press:

• F5 → Start debugging
• Ctrl+F5 → Run without debugging

When debugging starts, VS Code:

• Launches a PowerShell session
• Loads your script
• Pauses at the first breakpoint (if any)
• Opens the debugging panel

3. Breakpoints¶

Breakpoints tell the debugger where to pause execution so you can inspect the state of your script.

3.1 Setting a breakpoint¶

Click in the left margin next to a line of code, or press:

• F9 → Toggle breakpoint

A red dot appears, indicating the breakpoint is active.

3.2 Types of breakpoints¶

• Line breakpoints — pause at a specific line
• Conditional breakpoints — pause only when a condition is true
• Function breakpoints — pause when a specific function is called
• Data breakpoints (PowerShell 7+) — pause when a variable changes

3.3 Conditional breakpoint example¶

Right‑click a breakpoint → Edit Breakpoint → add a condition:

$i -eq 5

The debugger pauses only when $i equals 5.

4. Stepping Through Code¶

Once the debugger is paused, you can control execution:

These controls let you follow the script’s logic line‑by‑line.

5. Inspecting Variables¶

The Run and Debug panel shows:

• Local variables
• Script‑scope variables
• Global variables
• Call stack

You can expand objects to inspect their properties.

5.1 Hover inspection¶

Hover your mouse over a variable:

$items = Get-ChildItem

VS Code displays its current value in a tooltip.

5.2 Debug Console¶

The Debug Console lets you run PowerShell commands in the context of the paused script.

Example:

$items.Count

This is extremely useful for inspecting state without modifying the script.

6. Using the Call Stack¶

The Call Stack panel shows the chain of function calls that led to the current line.

Example:

Main.ps1 → Process-Data → Validate-Item

You can click any frame to jump to that function’s source code.

This is invaluable when debugging nested functions or modules.

7. Logging and Output Tools¶

VS Code integrates with PowerShell’s built‑in logging:

• Write-Debug
• Write-Verbose
• Write-Information
• Write-Warning
• Write-Error

Enable debug/verbose output in the Debug Console:

$DebugPreference = "Continue"
$VerbosePreference = "Continue"

These messages appear in the integrated terminal during debugging.

8. Debugging PowerShell Modules¶

When debugging module code:

1. Open the module folder in VS Code
2. Press F5 to start a PowerShell debugging session
3. Import the module manually or via a startup script
4. Set breakpoints inside module functions

VS Code pauses execution even inside imported modules.

9. Debugging Remote Sessions¶

The PowerShell extension supports remote debugging via:

• PowerShell Remoting (Enter-PSSession)
• SSH connections
• PowerShell 7 remoting endpoints

You can debug scripts running on remote machines just like local ones.

10. Summary¶

VS Code provides a full suite of debugging tools:

These tools make it dramatically easier to diagnose issues, understand script behavior, and build reliable PowerShell code.