This is the built-in help made by Microsoft for the command 'Set-PSBreakpoint', in PowerShell version 2 - as retrieved from
Windows version 'Microsoft® Windows Vista™ Ultimate ' PowerShell help files on 2016-06-23.
For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.
Sets a breakpoint on a line, command, or variable.
Set-PSBreakpoint -Command <string[]> [[-Script] <string[]>] [-Action <scriptblock>] [<CommonParameters>]
Set-PSBreakpoint [-Script] <string[]> [-Line] <Int32[]> [[-Column] <int>] [-Action <scriptblock>] [<CommonParameters>]
Set-PSBreakpoint -Variable <string[]> [[-Script] <string[]>] [-Mode {Read | Write | ReadWrite}] [-Action <scriptblock>] [<CommonParameters>]
The Set-PSBreakpoint cmdlet sets a breakpoint in a script or in any command run in the current session. You can use Set-PSBreakpoint to set a br
eakpoint before executing a script or running a command, or during debugging, when stopped at another breakpoint.
Note: Set-PSBreakpoint cannot set a breakpoint on a remote computer. To debug a script on a remote computer, copy the script to the local compute
r and then debug it locally.
Each Set-PSBreakpoint command creates one of the following three types of breakpoints:
-- Line breakpoint: Sets breakpoints at particular line and column coordinates.
-- Command breakpoint: Sets breakpoints on commands and functions.
-- Variable breakpoint: Sets breakpoints on variables.
You can set a breakpoint on multiple lines, commands, or variables in a single Set-PSBreakpoint command, but each Set-PSBreakpoint command sets o
nly one type of breakpoint.
At a breakpoint, Windows PowerShell temporarily stops executing and gives control to the debugger. The command prompt changes to "DBG>", and a se
t of debugger commands become available for use. However, you can use the Action parameter to specify an alternate response, such as conditions f
or the breakpoint or instructions to perform additional tasks such as logging or diagnostics.
The Set-PSBreakpoint cmdlet is one of several cmdlets designed for debugging Windows PowerShell scripts. For more information about the Windows P
owerShell debugger, see about_Debuggers.
<
Online version: http://go.microsoft.com/fwlink/?LinkID=113449
about_Debuggers
Get-PSBreakpoint
Enable-PSBreakpoint
Disable-PSBreakpoint
Remove-PSBreakpoint
Get-PSCallStack
<
-------------------------- EXAMPLE 1 --------------------------
C:\PS>set-psbreakpoint -script sample.ps1 -line 5
Column : 0
Line : 5
Action :
Enabled : True
HitCount : 0
Id : 0
Script : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1
Description
-----------
This command sets a breakpoint at line 5 in the Sample.ps1 script. As a result, when the script runs, execution stops immediately before line 5 w
ould execute.
When you set a new breakpoint by line number, the Set-PSBreakpoint cmdlet generates a line breakpoint object (System.Management.Automation.LineBr
eakpoint) that includes the breakpoint ID and hit count, as shown in the following sample output.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>set-psbreakpoint -command Increment -script sample.ps1
Command : Increment
Action :
Enabled : True
HitCount : 0
Id : 1
Script : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1
Description
-----------
This command creates a command breakpoint on the Increment function in the Sample.ps1 cmdlet. The script stops executing immediately before each
call to the specified function.
The result is a command breakpoint object. Before the script runs, the value of the HitCount property is 0.
-------------------------- EXAMPLE 3 --------------------------
C:\PS>set-psbreakpoint -script sample.ps1 -variable Server -Mode ReadWrite
Description
-----------
This command sets a breakpoint on the Server variable in the Sample.ps1 script. It uses the Mode parameter with a value of ReadWrite to stop exec
ution when the value of the variable is read and just before the value changes.
-------------------------- EXAMPLE 4 --------------------------
C:\PS>set-psbreakpoint -script Sample.ps1 -command "write*"
Description
-----------
This command sets a breakpoint on every command in the Sample.ps1 script that begins with "write", such as "write-host".
-------------------------- EXAMPLE 5 --------------------------
C:\PS>set-psbreakpoint -script test.ps1 -command DiskTest `
-action { (if $disk -gt 2) { break } }
Description
-----------
This command stops execution at the DiskTest function in the Test.ps1 script only when the value of the $disk variable is greater than 2.
It uses the Set-PSBreakpoint cmdlet to set a command breakpoint on the DiskTest function. The value of the action is a script block that tests th
e value of the $disk variable in the function.
The action uses the BREAK keyword to stop execution if the condition is met. The alternative (and the default) is CONTINUE.
-------------------------- EXAMPLE 6 --------------------------
C:\PS>set-psbreakpoint -command checkpoint-computer
Id : 0
Command : checkpoint-computer
Enabled : True
HitCount : 0
Action :
C:\PS> function CheckLog {
>> get-eventlog -log Application |
>> where {($_.source -like "TestApp") -and ($_.Message -like "*failed*")}
>>}
>>
C:\PS> Checklog
DEBUG: Hit breakpoint(s)
DEBUG: Function breakpoint on 'prompt:Checklog'
C:\PS>>>
Description
-----------
This command sets a breakpoint on the CheckLog function. Because the command does not specify a script, the breakpoint is set on anything that ru
ns in the current session. The debugger breaks when the function is called, not when it is declared.
-------------------------- EXAMPLE 7 --------------------------
C:\PS>set-psbreakpoint -script sample.ps1 -line 1, 14, 19 -column 2 -action {&(log.ps1)}
Column : 2
Line : 1
Action :
Enabled : True
HitCount : 0
Id : 6
Script : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1
Column : 2
Line : 14
Action :
Enabled : True
HitCount : 0
Id : 7
Script : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1
Column : 2
Line : 19
Action :
Enabled : True
HitCount : 0
Id : 8
Script : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1
Description
-----------
This command sets three line breakpoints in the Sample.ps1 script. It sets one breakpoint at column 2 on each of the lines specified in the scrip
t. The action specified in the Action parameter applies to all breakpoints.