diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Wait-Debugger.md b/reference/5.1/Microsoft.PowerShell.Utility/Wait-Debugger.md index 9415567ddf61..a85050c9fa12 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Wait-Debugger.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Wait-Debugger.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 09/03/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/wait-debugger?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Wait-Debugger @@ -22,17 +22,78 @@ Wait-Debugger [] ## DESCRIPTION Stops the PowerShell script execution engine at the point immediately after the `Wait-Debugger` -cmdlet and waits for a debugger to be attached. This is similar to using -`Enable-RunspaceDebug -BreakAll` in a DSC resource but breaks at a specific point in the script. +cmdlet and waits for a debugger to be attached. > [!CAUTION] > Make sure you remove the `Wait-Debugger` lines after you are done. A running script appears to be -> hung when it is stopped at a `Wait-Debugger`. +> hung when it's stopped at a `Wait-Debugger`. + +For more information about debugging in PowerShell, see +[about_Debuggers](/powershell/module/microsoft.powershell.core/about/about_debuggers). ## EXAMPLES ### Example 1: Insert breakpoint for debugging +The file `dbgtest.ps1` contains a function `Test-Condition`. The `Wait-Debugger` command was +inserted in the function to stop the script execution at that point. When you run the function, the +script stops at the `Wait-Debugger` line and enters the command-line debugger. The `l` command lists +the script lines, and you can use other debugger commands to inspect the script state. + +```powershell +function Test-Condition { + [CmdletBinding()] + param ( + [Parameter(Mandatory)] + [string]$Name, + [string]$Message = "Hello, $Name!" + ) + + if ($Name -eq $env:USERNAME) { + Write-Output "$Message" + } else { + # Remove after debugging + Wait-Debugger + + Write-Output "$Name is not the current user." + } +} +``` + +``` +PS D:\> Test-Condition Fred +Entering debug mode. Use h or ? for help. + +At D:\temp\test\dbgtest.ps1:13 char:9 ++ Wait-Debugger ++ ~~~~~~~~~~~~~ +[DBG]: PS D:\>> l + + 8: + 9: if ($Name -eq $env:USERNAME) { + 10: Write-Output "$Message" + 11: } else { + 12: # Remove after debugging + 13:* Wait-Debugger + 14: + 15: Write-Output "$Name is not the current user." + 16: } + 17: } + +[DBG]: PS D:\>> $env:USERNAME +User01 +[DBG]: PS D:\>> exit +PS D:\> +``` + +Notice that output from the `l` shows that the script execution is stopped at the `Wait-Debugger` on +line 13. + +### Example 2: Insert breakpoint for debugging a DSC resource + +In this example, the `Wait-Debugger` command was inserted in the `CopyFile` method of a DSC +resource. This is similar to using `Enable-RunspaceDebug -BreakAll` in a DSC resource but breaks at +a specific point in the script. ``` [DscResource()] class FileResource @@ -50,76 +111,53 @@ class FileResource [Nullable[datetime]] $CreationTime - [void] Set() - { + [void] Set() { $fileExists = $this.TestFilePath($this.Path) - if ($this.ensure -eq [Ensure]::Present) - { - if (! $fileExists) - { + if ($this.ensure -eq [Ensure]::Present) { + if (! $fileExists) { $this.CopyFile() } - } - else - { - if ($fileExists) - { + } else { + if ($fileExists) { Write-Verbose -Message "Deleting the file $($this.Path)" Remove-Item -LiteralPath $this.Path -Force } } } - [bool] Test() - { + [bool] Test() { $present = Test-Path -LiteralPath $this.Path - - if ($this.Ensure -eq [Ensure]::Present) - { + if ($this.Ensure -eq [Ensure]::Present) { return $present - } - else - { + } else { return (! $present) } } - [FileResource] Get() - { + [FileResource] Get() { $present = Test-Path -Path $this.Path - - if ($present) - { + if ($present) { $file = Get-ChildItem -LiteralPath $this.Path $this.CreationTime = $file.CreationTime $this.Ensure = [Ensure]::Present - } - else - { + } else { $this.CreationTime = $null $this.Ensure = [Ensure]::Absent } - return $this } - [void] CopyFile() - { + [void] CopyFile() { # Testing only - Remove before deployment! Wait-Debugger - if (! (Test-Path -LiteralPath $this.SourcePath)) - { + if (! (Test-Path -LiteralPath $this.SourcePath)) { throw "SourcePath $($this.SourcePath) is not found." } - - if (Test-Path -LiteralPath $this.Path -PathType Container) - { + if (Test-Path -LiteralPath $this.Path -PathType Container) { throw "Path $($this.Path) is a directory path" } - Write-Verbose "Copying $($this.SourcePath) to $($this.Path)" - Copy-Item -LiteralPath $this.SourcePath -Destination $this.Path -Force } } @@ -131,7 +169,8 @@ class FileResource This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -150,3 +189,5 @@ This cmdlet returns no output. ## RELATED LINKS [Enable-DscDebug](/powershell/module/PSDesiredStateConfiguration/Enable-DscDebug) + +[about_Debuggers](/powershell/module/microsoft.powershell.core/about/about_debuggers) diff --git a/reference/7.2/Microsoft.PowerShell.Utility/Wait-Debugger.md b/reference/7.2/Microsoft.PowerShell.Utility/Wait-Debugger.md index 3b1672ed7068..9bf72c37e473 100644 --- a/reference/7.2/Microsoft.PowerShell.Utility/Wait-Debugger.md +++ b/reference/7.2/Microsoft.PowerShell.Utility/Wait-Debugger.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 09/03/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/wait-debugger?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Wait-Debugger @@ -22,17 +22,78 @@ Wait-Debugger [] ## DESCRIPTION Stops the PowerShell script execution engine at the point immediately after the `Wait-Debugger` -cmdlet and waits for a debugger to be attached. This is similar to using -`Enable-RunspaceDebug -BreakAll` in a DSC resource but breaks at a specific point in the script. +cmdlet and waits for a debugger to be attached. > [!CAUTION] > Make sure you remove the `Wait-Debugger` lines after you are done. A running script appears to be -> hung when it is stopped at a `Wait-Debugger`. +> hung when it's stopped at a `Wait-Debugger`. + +For more information about debugging in PowerShell, see +[about_Debuggers](/powershell/module/microsoft.powershell.core/about/about_debuggers). ## EXAMPLES ### Example 1: Insert breakpoint for debugging +The file `dbgtest.ps1` contains a function `Test-Condition`. The `Wait-Debugger` command was +inserted in the function to stop the script execution at that point. When you run the function, the +script stops at the `Wait-Debugger` line and enters the command-line debugger. The `l` command lists +the script lines, and you can use other debugger commands to inspect the script state. + +```powershell +function Test-Condition { + [CmdletBinding()] + param ( + [Parameter(Mandatory)] + [string]$Name, + [string]$Message = "Hello, $Name!" + ) + + if ($Name -eq $env:USERNAME) { + Write-Output "$Message" + } else { + # Remove after debugging + Wait-Debugger + + Write-Output "$Name is not the current user." + } +} +``` + +``` +PS D:\> Test-Condition Fred +Entering debug mode. Use h or ? for help. + +At D:\temp\test\dbgtest.ps1:13 char:9 ++ Wait-Debugger ++ ~~~~~~~~~~~~~ +[DBG]: PS D:\>> l + + 8: + 9: if ($Name -eq $env:USERNAME) { + 10: Write-Output "$Message" + 11: } else { + 12: # Remove after debugging + 13:* Wait-Debugger + 14: + 15: Write-Output "$Name is not the current user." + 16: } + 17: } + +[DBG]: PS D:\>> $env:USERNAME +User01 +[DBG]: PS D:\>> exit +PS D:\> +``` + +Notice that output from the `l` shows that the script execution is stopped at the `Wait-Debugger` on +line 13. + +### Example 2: Insert breakpoint for debugging a DSC resource + +In this example, the `Wait-Debugger` command was inserted in the `CopyFile` method of a DSC +resource. This is similar to using `Enable-RunspaceDebug -BreakAll` in a DSC resource but breaks at +a specific point in the script. ``` [DscResource()] class FileResource @@ -50,76 +111,53 @@ class FileResource [Nullable[datetime]] $CreationTime - [void] Set() - { + [void] Set() { $fileExists = $this.TestFilePath($this.Path) - if ($this.ensure -eq [Ensure]::Present) - { - if (! $fileExists) - { + if ($this.ensure -eq [Ensure]::Present) { + if (! $fileExists) { $this.CopyFile() } - } - else - { - if ($fileExists) - { + } else { + if ($fileExists) { Write-Verbose -Message "Deleting the file $($this.Path)" Remove-Item -LiteralPath $this.Path -Force } } } - [bool] Test() - { + [bool] Test() { $present = Test-Path -LiteralPath $this.Path - - if ($this.Ensure -eq [Ensure]::Present) - { + if ($this.Ensure -eq [Ensure]::Present) { return $present - } - else - { + } else { return (! $present) } } - [FileResource] Get() - { + [FileResource] Get() { $present = Test-Path -Path $this.Path - - if ($present) - { + if ($present) { $file = Get-ChildItem -LiteralPath $this.Path $this.CreationTime = $file.CreationTime $this.Ensure = [Ensure]::Present - } - else - { + } else { $this.CreationTime = $null $this.Ensure = [Ensure]::Absent } - return $this } - [void] CopyFile() - { + [void] CopyFile() { # Testing only - Remove before deployment! Wait-Debugger - if (! (Test-Path -LiteralPath $this.SourcePath)) - { + if (! (Test-Path -LiteralPath $this.SourcePath)) { throw "SourcePath $($this.SourcePath) is not found." } - - if (Test-Path -LiteralPath $this.Path -PathType Container) - { + if (Test-Path -LiteralPath $this.Path -PathType Container) { throw "Path $($this.Path) is a directory path" } - Write-Verbose "Copying $($this.SourcePath) to $($this.Path)" - Copy-Item -LiteralPath $this.SourcePath -Destination $this.Path -Force } } @@ -131,7 +169,8 @@ class FileResource This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -150,3 +189,5 @@ This cmdlet returns no output. ## RELATED LINKS [Enable-DscDebug](/powershell/module/PSDesiredStateConfiguration/Enable-DscDebug) + +[about_Debuggers](/powershell/module/microsoft.powershell.core/about/about_debuggers) diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Wait-Debugger.md b/reference/7.4/Microsoft.PowerShell.Utility/Wait-Debugger.md index 9815a9a3d5fa..276dfe784e19 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Wait-Debugger.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Wait-Debugger.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 09/03/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/wait-debugger?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Wait-Debugger @@ -22,17 +22,78 @@ Wait-Debugger [] ## DESCRIPTION Stops the PowerShell script execution engine at the point immediately after the `Wait-Debugger` -cmdlet and waits for a debugger to be attached. This is similar to using -`Enable-RunspaceDebug -BreakAll` in a DSC resource but breaks at a specific point in the script. +cmdlet and waits for a debugger to be attached. > [!CAUTION] > Make sure you remove the `Wait-Debugger` lines after you are done. A running script appears to be -> hung when it is stopped at a `Wait-Debugger`. +> hung when it's stopped at a `Wait-Debugger`. + +For more information about debugging in PowerShell, see +[about_Debuggers](/powershell/module/microsoft.powershell.core/about/about_debuggers). ## EXAMPLES ### Example 1: Insert breakpoint for debugging +The file `dbgtest.ps1` contains a function `Test-Condition`. The `Wait-Debugger` command was +inserted in the function to stop the script execution at that point. When you run the function, the +script stops at the `Wait-Debugger` line and enters the command-line debugger. The `l` command lists +the script lines, and you can use other debugger commands to inspect the script state. + +```powershell +function Test-Condition { + [CmdletBinding()] + param ( + [Parameter(Mandatory)] + [string]$Name, + [string]$Message = "Hello, $Name!" + ) + + if ($Name -eq $env:USERNAME) { + Write-Output "$Message" + } else { + # Remove after debugging + Wait-Debugger + + Write-Output "$Name is not the current user." + } +} +``` + +``` +PS D:\> Test-Condition Fred +Entering debug mode. Use h or ? for help. + +At D:\temp\test\dbgtest.ps1:13 char:9 ++ Wait-Debugger ++ ~~~~~~~~~~~~~ +[DBG]: PS D:\>> l + + 8: + 9: if ($Name -eq $env:USERNAME) { + 10: Write-Output "$Message" + 11: } else { + 12: # Remove after debugging + 13:* Wait-Debugger + 14: + 15: Write-Output "$Name is not the current user." + 16: } + 17: } + +[DBG]: PS D:\>> $env:USERNAME +User01 +[DBG]: PS D:\>> exit +PS D:\> +``` + +Notice that output from the `l` shows that the script execution is stopped at the `Wait-Debugger` on +line 13. + +### Example 2: Insert breakpoint for debugging a DSC resource + +In this example, the `Wait-Debugger` command was inserted in the `CopyFile` method of a DSC +resource. This is similar to using `Enable-RunspaceDebug -BreakAll` in a DSC resource but breaks at +a specific point in the script. ``` [DscResource()] class FileResource @@ -50,76 +111,53 @@ class FileResource [Nullable[datetime]] $CreationTime - [void] Set() - { + [void] Set() { $fileExists = $this.TestFilePath($this.Path) - if ($this.ensure -eq [Ensure]::Present) - { - if (! $fileExists) - { + if ($this.ensure -eq [Ensure]::Present) { + if (! $fileExists) { $this.CopyFile() } - } - else - { - if ($fileExists) - { + } else { + if ($fileExists) { Write-Verbose -Message "Deleting the file $($this.Path)" Remove-Item -LiteralPath $this.Path -Force } } } - [bool] Test() - { + [bool] Test() { $present = Test-Path -LiteralPath $this.Path - - if ($this.Ensure -eq [Ensure]::Present) - { + if ($this.Ensure -eq [Ensure]::Present) { return $present - } - else - { + } else { return (! $present) } } - [FileResource] Get() - { + [FileResource] Get() { $present = Test-Path -Path $this.Path - - if ($present) - { + if ($present) { $file = Get-ChildItem -LiteralPath $this.Path $this.CreationTime = $file.CreationTime $this.Ensure = [Ensure]::Present - } - else - { + } else { $this.CreationTime = $null $this.Ensure = [Ensure]::Absent } - return $this } - [void] CopyFile() - { + [void] CopyFile() { # Testing only - Remove before deployment! Wait-Debugger - if (! (Test-Path -LiteralPath $this.SourcePath)) - { + if (! (Test-Path -LiteralPath $this.SourcePath)) { throw "SourcePath $($this.SourcePath) is not found." } - - if (Test-Path -LiteralPath $this.Path -PathType Container) - { + if (Test-Path -LiteralPath $this.Path -PathType Container) { throw "Path $($this.Path) is a directory path" } - Write-Verbose "Copying $($this.SourcePath) to $($this.Path)" - Copy-Item -LiteralPath $this.SourcePath -Destination $this.Path -Force } } @@ -131,7 +169,8 @@ class FileResource This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -150,3 +189,5 @@ This cmdlet returns no output. ## RELATED LINKS [Enable-DscDebug](/powershell/module/PSDesiredStateConfiguration/Enable-DscDebug) + +[about_Debuggers](/powershell/module/microsoft.powershell.core/about/about_debuggers) diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Wait-Debugger.md b/reference/7.5/Microsoft.PowerShell.Utility/Wait-Debugger.md index 6c3fcba35182..12f36c330446 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Wait-Debugger.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Wait-Debugger.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 09/03/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/wait-debugger?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Wait-Debugger @@ -22,17 +22,78 @@ Wait-Debugger [] ## DESCRIPTION Stops the PowerShell script execution engine at the point immediately after the `Wait-Debugger` -cmdlet and waits for a debugger to be attached. This is similar to using -`Enable-RunspaceDebug -BreakAll` in a DSC resource but breaks at a specific point in the script. +cmdlet and waits for a debugger to be attached. > [!CAUTION] > Make sure you remove the `Wait-Debugger` lines after you are done. A running script appears to be -> hung when it is stopped at a `Wait-Debugger`. +> hung when it's stopped at a `Wait-Debugger`. + +For more information about debugging in PowerShell, see +[about_Debuggers](/powershell/module/microsoft.powershell.core/about/about_debuggers). ## EXAMPLES ### Example 1: Insert breakpoint for debugging +The file `dbgtest.ps1` contains a function `Test-Condition`. The `Wait-Debugger` command was +inserted in the function to stop the script execution at that point. When you run the function, the +script stops at the `Wait-Debugger` line and enters the command-line debugger. The `l` command lists +the script lines, and you can use other debugger commands to inspect the script state. + +```powershell +function Test-Condition { + [CmdletBinding()] + param ( + [Parameter(Mandatory)] + [string]$Name, + [string]$Message = "Hello, $Name!" + ) + + if ($Name -eq $env:USERNAME) { + Write-Output "$Message" + } else { + # Remove after debugging + Wait-Debugger + + Write-Output "$Name is not the current user." + } +} +``` + +``` +PS D:\> Test-Condition Fred +Entering debug mode. Use h or ? for help. + +At D:\temp\test\dbgtest.ps1:13 char:9 ++ Wait-Debugger ++ ~~~~~~~~~~~~~ +[DBG]: PS D:\>> l + + 8: + 9: if ($Name -eq $env:USERNAME) { + 10: Write-Output "$Message" + 11: } else { + 12: # Remove after debugging + 13:* Wait-Debugger + 14: + 15: Write-Output "$Name is not the current user." + 16: } + 17: } + +[DBG]: PS D:\>> $env:USERNAME +User01 +[DBG]: PS D:\>> exit +PS D:\> +``` + +Notice that output from the `l` shows that the script execution is stopped at the `Wait-Debugger` on +line 13. + +### Example 2: Insert breakpoint for debugging a DSC resource + +In this example, the `Wait-Debugger` command was inserted in the `CopyFile` method of a DSC +resource. This is similar to using `Enable-RunspaceDebug -BreakAll` in a DSC resource but breaks at +a specific point in the script. ``` [DscResource()] class FileResource @@ -50,76 +111,53 @@ class FileResource [Nullable[datetime]] $CreationTime - [void] Set() - { + [void] Set() { $fileExists = $this.TestFilePath($this.Path) - if ($this.ensure -eq [Ensure]::Present) - { - if (! $fileExists) - { + if ($this.ensure -eq [Ensure]::Present) { + if (! $fileExists) { $this.CopyFile() } - } - else - { - if ($fileExists) - { + } else { + if ($fileExists) { Write-Verbose -Message "Deleting the file $($this.Path)" Remove-Item -LiteralPath $this.Path -Force } } } - [bool] Test() - { + [bool] Test() { $present = Test-Path -LiteralPath $this.Path - - if ($this.Ensure -eq [Ensure]::Present) - { + if ($this.Ensure -eq [Ensure]::Present) { return $present - } - else - { + } else { return (! $present) } } - [FileResource] Get() - { + [FileResource] Get() { $present = Test-Path -Path $this.Path - - if ($present) - { + if ($present) { $file = Get-ChildItem -LiteralPath $this.Path $this.CreationTime = $file.CreationTime $this.Ensure = [Ensure]::Present - } - else - { + } else { $this.CreationTime = $null $this.Ensure = [Ensure]::Absent } - return $this } - [void] CopyFile() - { + [void] CopyFile() { # Testing only - Remove before deployment! Wait-Debugger - if (! (Test-Path -LiteralPath $this.SourcePath)) - { + if (! (Test-Path -LiteralPath $this.SourcePath)) { throw "SourcePath $($this.SourcePath) is not found." } - - if (Test-Path -LiteralPath $this.Path -PathType Container) - { + if (Test-Path -LiteralPath $this.Path -PathType Container) { throw "Path $($this.Path) is a directory path" } - Write-Verbose "Copying $($this.SourcePath) to $($this.Path)" - Copy-Item -LiteralPath $this.SourcePath -Destination $this.Path -Force } } @@ -131,7 +169,8 @@ class FileResource This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -150,3 +189,5 @@ This cmdlet returns no output. ## RELATED LINKS [Enable-DscDebug](/powershell/module/PSDesiredStateConfiguration/Enable-DscDebug) + +[about_Debuggers](/powershell/module/microsoft.powershell.core/about/about_debuggers)