Edit

Write-Debug

  • Reference
Module:
Microsoft.PowerShell.Utility

Writes a debug message to the console.

Syntax

Write-Debug
     [-Message] <String>
     [<CommonParameters>]

Description

The Write-Debug cmdlet writes debug messages to the host from a script or command.

By default, debug messages are not displayed in the console, but you can display them by using the Debug parameter or the $DebugPreference variable.

Examples

Example 1: Understand $DebugPreference

This example writes a debug message.

Write-Debug "Cannot open file."

The default value of $DebugPreference is SilentlyContinue. Therefore, the message is not displayed in the console.

Example 2: Change the value of $DebugPreference

This example shows the effect of changing the value of the $DebugPreference variable. First, we display the current value of $DebugPreference and attempt to write a debug message. Then we change the value of $DebugPreference to Continue, which allows debug messages to be displayed.

PS> $DebugPreference
SilentlyContinue
PS> Write-Debug "Cannot open file."
PS>
PS> $DebugPreference = "Continue"
PS> Write-Debug "Cannot open file."
DEBUG: Cannot open file.

For more information about $DebugPreference, see about_Preference_Variables.

Example 3: Use the Debug parameter to override $DebugPreference

The Test-Debug function writes the value of the $DebugPreference variable to the PowerShell host and to the Debug stream. In this example, we use the Debug parameter to override the $DebugPreference value.

function Test-Debug {
    [CmdletBinding()]
    param()
    Write-Debug ('$DebugPreference is ' + $DebugPreference)
    Write-Host ('$DebugPreference is ' + $DebugPreference)
}

PS> Test-Debug
$DebugPreference is SilentlyContinue

PS> Test-Debug -Debug
DEBUG: $DebugPreference is Inquire

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):
$DebugPreference is Inquire
PS> $DebugPreference
SilentlyContinue

Notice that the value of $DebugPreference changes when you use the Debug parameter. This change only affects the scope of the function. The value is not affected outside the function.

Note

When the value of $DebugPreference is Inquire, PowerShell halts execution to ask if execution should continue.

For more information about the Debug common parameter, see about_CommonParameters.

Parameters

-Message

Specifies the debug message to send to the console.

Type:String
Aliases:Msg
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

Inputs

String

You can pipe a string that contains a debug message to this cmdlet.

Outputs

None

This cmdlet returns no output. It only writes to the debug stream.