PowerShell Cmdlet Deep Dive: Write-Debug

Welcome to Wahmans PowerShell blog! In today’s post, we’re exploring a powerful, but sometimes overlooked, cmdlet: Write-Debug. The official Microsoft documentation describes Write-Debug simply as:

Writes a debug message to the console.

But there’s more to it! Write-Debug is a fantastic tool for diagnosing issues in your scripts during development. These messages are only shown when the $DebugPreference variable is set to Continue. Let’s walk through this with a series of examples ranging from beginner to advanced use cases.

🔰 Example 1: Your First Debug Message

Write-Debug "This is a debug message"

To see this in action, you’ll first need to set the $DebugPreference variable:

$DebugPreference = "Continue"
Write-Debug "This is a debug message"

Output:

DEBUG: This is a debug message

🔍 Example 2: Debugging a Conditional Block

$DebugPreference = "Continue"
$name = "Peter"

if ($name -eq "Peter") {
    Write-Debug "Correct name detected: $name"
    Write-Host "Hello, $name!"
} else {
    Write-Debug "Name did not match. Input: $name"
    Write-Host "Access Denied."
}

This can be very helpful when validating logic inside conditionals.

🧰 Example 3: Debugging Within Functions

function Test-UserLogin {
    param(
        [string]$Username
    )

    Write-Debug "Testing user login for: $Username"
  
    if ($Username -in 'admin','wahman','developer') {
        Write-Debug "$Username is an authorized user"
        return $true
    } else {
        Write-Debug "$Username is NOT an authorized user"
        return $false
    }
}

$DebugPreference = "Continue"

Test-UserLogin -Username "wahman"

That’s a lightweight way to get insight into a function’s behavior while avoiding full verbose logging.

🧠 Example 4: Advanced Use — Conditional Debugging

function Start-ProcessWithDebugLogging {
    param(
        [string]$ProcessName,
        [switch]$EnableDebug
    )

    if ($EnableDebug) {
        $DebugPreference = "Continue"
        Write-Debug "Debugging enabled for Start-ProcessWithDebugLogging"
    } else {
        $DebugPreference = "SilentlyContinue"
    }

    Write-Debug "Attempting to start process: $ProcessName"

    try {
        Start-Process -FilePath $ProcessName -ErrorAction Stop
        Write-Debug "Process $ProcessName started successfully"
    } catch {
        Write-Debug "Failed to start process: $_"
        Write-Host "Error starting process: $_"
    }
}

Start-ProcessWithDebugLogging -ProcessName "notepad.exe" -EnableDebug

This technique gives your script users control over debugging output, without modifying code and keeping UIs clean in production.

📝 Summary

Write-Debug is great for non-intrusive development-time logging
It respects the $DebugPreference setting
Use it with care: it won’t show anything by default!
Allows fine-grained debugging without exposing unnecessary verbosity

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

Wahmans Powershell Blog

Write-Debug