PowerShell Logo Small

Set-PSBreakpoint



This is the built-in help made by Microsoft for the command 'Set-PSBreakpoint', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' 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.

SYNOPSIS

Sets a breakpoint on a line, command, or variable.

SYNTAX


Set-PSBreakpoint [-Script] <String[]> [-Line] <Int32[]> [[-Column] [<Int32>]] [-Action [<ScriptBlock>]] [-InformationAction {SilentlyContinue | Stop | Continue | Inquire |
Ignore | Suspend}] [-InformationVariable [<System.String>]] [<CommonParameters>]
Set-PSBreakpoint [[-Script] <String[]>] [-Action [<ScriptBlock>]] [-InformationAction {SilentlyContinue | Stop | Continue | Inquire | Ignore | Suspend}]
[-InformationVariable [<System.String>]] -Command <String[]> [<CommonParameters>]
Set-PSBreakpoint [[-Script] <String[]>] [-Action [<ScriptBlock>]] [-InformationAction {SilentlyContinue | Stop | Continue | Inquire | Ignore | Suspend}]
[-InformationVariable [<System.String>]] [-Mode {Read | Write | ReadWrite}] -Variable <String[]> [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


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 breakpoint 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 computer 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 only 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 set of debugger commands
become available for use. However, you can use the Action parameter to specify an alternate response, such as conditions for 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 PowerShell debugger, see
about_Debuggers.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=294013
Disable-PSBreakpoint
Enable-PSBreakpoint
Get-PSBreakpoint
Get-PSCallStack
Remove-PSBreakpoint
about_Debuggers

REMARKS

<

Examples


-------------------------- EXAMPLE 1 --------------------------

PS C:\>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



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 would execute.

When you set a new breakpoint by line number, the Set-PSBreakpoint cmdlet generates a line breakpoint object (System.Management.Automation.LineBreakpoint) that includes the
breakpoint ID and hit count, as shown in the following sample output.










-------------------------- EXAMPLE 2 --------------------------

PS C:\>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



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 --------------------------

PS C:\>set-psbreakpoint -script sample.ps1 -variable Server -Mode ReadWrite



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 execution when the value of the
variable is read and just before the value changes.










-------------------------- EXAMPLE 4 --------------------------

PS C:\>set-psbreakpoint -script Sample.ps1 -command "write*"



This command sets a breakpoint on every command in the Sample.ps1 script that begins with "write", such as "write-host".










-------------------------- EXAMPLE 5 --------------------------

PS C:\>set-psbreakpoint -script test.ps1 -command DiskTest `
-action { if ($disk -gt 2) { break } }



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 the 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 --------------------------

PS C:\>set-psbreakpoint -command checklog

Id : 0
Command : checkkog
Enabled : True
HitCount : 0
Action :

PS C:\>function CheckLog {
>> get-eventlog -log Application |
>> where {($_.source -like "TestApp") -and ($_.Message -like "*failed*")}
>>}
>>
PS C:\>Checklog
DEBUG: Hit breakpoint(s)
DEBUG: Function breakpoint on 'prompt:Checklog'
PS C:\>>>



This command sets a breakpoint on the CheckLog function. Because the command does not specify a script, the breakpoint is set on anything that runs in the current session.
The debugger breaks when the function is called, not when it is declared.










-------------------------- EXAMPLE 7 --------------------------

PS C:\>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



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 script. The action specified in
the Action parameter applies to all breakpoints.