Using Wait-Debugger in PowerShell: A Developer’s Secret Weapon

Welcome back to Wahmans PowerShell blog! Today, we’re diving into a small but powerful cmdlet that can greatly improve your scripting and debugging process: Wait-Debugger.

What is Wait-Debugger?

Wait-Debugger is a cmdlet in PowerShell that halts the script execution and attaches the debugger before running the next statement. This is incredibly useful when you want to inspect or troubleshoot your code without manually setting breakpoints.

The official Microsoft documentation describes it as: "Stops a script in the debugger before running the next statement in the script."

When and Why to Use Wait-Debugger

When writing complex functions or scripts and want to inspect state at a specific point
While creating reusable modules to validate intermediate results
When building advanced workflows and needing precise execution control

Examples of Using Wait-Debugger

Example 1: Basic Usage

Write-Output "Step 1 Complete" 
Wait-Debugger
Write-Output "Step 2 Complete"

This script outputs the first step and then immediately halts execution at Wait-Debugger. You can now interact with the debugger to inspect variables or step through the script manually.

Example 2: Within a Function

function Test-Script {
    $x = 5
    $y = 10
    Wait-Debugger
    $sum = $x + $y
    Write-Output "Sum is $sum"
}

Test-Script

Here, the function pauses before calculating the sum, letting you check the values of $x and $y first.

Example 3: Conditional Debugging

$debugMode = $true

if ($debugMode) {
    Wait-Debugger
}

Write-Output "Running script with debug mode: $debugMode"

This pattern enables conditional debugging. Toggle $debugMode to control whether to pause execution or not.

Example 4: Debugging in Advanced Functions

function Get-CriticalData {
    [CmdletBinding()] 
    param (
        [Parameter(Mandatory)]
        [string]$DataSource
    )

    Begin {
        Write-Verbose "Connecting to data source $DataSource"
        Wait-Debugger
    }
    Process {
        # Simulate fetching data
        $data = "Important Data from $DataSource"
        Write-Output $data
    }
    End {
        Write-Verbose "Completed retrieval process."
    }
}

Get-CriticalData -DataSource "ProdServer" -Verbose

This advanced example allows you to debug right as the connection begins in an advanced function. It’s great for troubleshooting tricky module-related behavior.

Conclusion

Wait-Debugger is a lightweight yet powerful tool for any PowerShell user looking to gain more control over their script’s flow and debugging process. Whether you’re just starting out or diving into complex automation, this cmdlet is a must-have in your toolkit.

Happy scripting, and I will see you in the next post!

Wahmans Powershell Blog

Wait-Debugger