{"id":72102,"date":"2015-07-17T00:01:00","date_gmt":"2015-07-17T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2015\/07\/17\/setting-a-breakpoint-on-a-variable\/"},"modified":"2019-02-18T09:46:58","modified_gmt":"2019-02-18T16:46:58","slug":"setting-a-breakpoint-on-a-variable","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/setting-a-breakpoint-on-a-variable\/","title":{"rendered":"Setting a Breakpoint on a Variable"},"content":{"rendered":"

Summary<\/strong>: Ed Wilson, Microsoft Scripting Guy, talks about using variable breakpoints with the Windows PowerShell debugger.\nHello Windows PowerShell scripting dudes and dudettes!<\/span><\/p>\n

Debugging Week continues, and today I am talking about using variable breakpoints with the Windows PowerShell debugger. Setting a breakpoint on line 1 of the script is useful for easily entering a debugging session. Setting a breakpoint on a variable can often make a problem with a script easy to detect. This is, of course, especially true when you have already determined that the problem is with a variable that is getting assigned a value or being ignored.<\/p>\n

The following table shows the three modes of operation that can be used when the breakpoint is specified for a variable. You specify these modes by using the -mode<\/b> parameter.<\/p>\n\n\n\n\n\n\n
\n

Access mode<\/strong><\/p>\n<\/td>\n

\n

Meaning<\/strong><\/p>\n<\/td>\n<\/tr>\n

\n

Write<\/p>\n<\/td>\n

\n

Stops execution immediately before a new value is written to the variable.<\/p>\n<\/td>\n<\/tr>\n

\n

Read<\/p>\n<\/td>\n

\n

Stops execution when the variable is read—that is, when its value is accessed, either to be assigned, displayed, or used. In read mode, execution does not stop when the value of the variable changes.<\/p>\n<\/td>\n<\/tr>\n

\n

ReadWrite<\/p>\n<\/td>\n

\n

Stops execution when the variable is read or written.<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

To see when a script named BadScript.ps1 script writes to the $num<\/b> variable, you use Write mode. When you specify the value for the -variable<\/b> parameter, do not include the dollar sign in front of the variable name.\nTo set a breakpoint on a variable, you only need to supply the path to the script, the name of the variable, and the access mode. When a variable breakpoint is set, the System.Management.Automation.LineBreak .NET Framework class object that is returned does not include the access mode value. This is true even if you use the Get-PSBreakpoint<\/b> cmdlet to directly access the breakpoint.\nIf you pipe the System.Management.Automation.LineBreak .NET Framework class object to the Format-List<\/b> cmdlet, you will be able to see that the access mode property is available. In this example, you set a breakpoint when the $num<\/b> variable is written to in the C:\\fso\\BadScript.ps1 script:<\/p>\n

PS C:\\> Set-PSBreakpoint -Variable num -Mode write -Script C:\\FSO\\BadScript.ps1
  ID Script            Line Command           Variable         Action
  — ——            —- ——-           ——–         ——
   3 BadScript.ps1                            num<\/p>\n

PS C:\\> Get-PSBreakpoint
  ID Script            Line Command           Variable         Action
  — ——            —- ——-           ——–         ——
   3 BadScript.ps1                            num<\/p>\n

PS C:\\> Get-PSBreakpoint  | Format-List * -Force
AccessMode : Write
Variable   : num
Action     :
Enabled    : True
HitCount   : 0
Id         : 3
Script     : C:\\FSO\\BadScript.ps1\nAfter setting the breakpoint, when you run the script (if the other breakpoints have been removed or deactivated, which will be discussed later), the script enters the Windows PowerShell debugger when the breakpoint is hit (that is, when the value of the $num<\/b> variable is written to).\nIf you step through the script by using the s<\/b> command, you will be able to follow the sequence of operations. Only one breakpoint is hit when the script is run. This is on line 48 when the value is set to 0.<\/p>\n

PS C:\\> C:\\fso\\BadScript.ps1<\/p>\n

Entering debug mode. Use h or ? for help.<\/p>\n

Hit Variable breakpoint on ‘C:\\fso\\BadScript.ps1:$num’ (Write access)<\/p>\n

At C:\\fso\\BadScript.ps1:43 char:1<\/p>\n

+ $num = 0<\/p>\n

+ ~~~~~~~~<\/p>\n

[DBG]: PS C:\\>> $num<\/p>\n

0<\/p>\n

[DBG]: PS C:\\>> Write-Host $num<\/p>\n

0<\/p>\n

[DBG]: PS C:\\>> s<\/p>\n

At C:\\fso\\BadScript.ps1:44 char:1<\/p>\n

+ SubOne($num) | DivideNum($num)<\/p>\n

+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<\/p>\n

[DBG]: PS C:\\>> $num<\/p>\n

0<\/p>\n

[DBG]: PS C:\\>> q<\/p>\n

PS C:\\><\/p>\n

Note<\/b>  To quickly remove all breakpoints from a Windows PowerShell session, use the Get-PSBreakpoint<\/b> cmdlet and pipe the output to the Remove-PSBreakpoint<\/b> cmdlet:<\/p>\n

Get-PSBreakpoint | Remove-PSBreakpoint\nTo set a breakpoint on a Read operation for the variable, you specify the -variable<\/b> parameter and the name of the variable, the -script<\/b> parameter with the path to the script, and Read<\/b> as the value for the -mode<\/b> parameter. This is shown here:<\/p>\n

PS C:\\> Set-PSBreakpoint -Variable num -Script C:\\FSO\\BadScript.ps1 -Mode read<\/p>\n

  ID Script            Line Command           Variable         Action
  — ——            —- ——-           ——–         ——
   4 BadScript.ps1                            num\nWhen you run the script, a breakpoint will be displayed each time you hit a Read operation on the variable. Each breakpoint will be displayed in the Windows PowerShell console as Hit Variable breakpoint, followed by the path to the script and the access mode of the variable.\nIn the BadScript.ps1 script, the value of the $num<\/b> variable is read several times. The truncated output is shown here:<\/p>\n

PS C:\\> C:\\fso\\BadScript.ps1<\/p>\n

Hit Variable breakpoint on ‘C:\\fso\\BadScript.ps1:$num’ (Read access)<\/p>\n

At C:\\fso\\BadScript.ps1:44 char:1<\/p>\n

+ SubOne($num) | DivideNum($num)<\/p>\n

+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<\/p>\n

[DBG]: PS C:\\>> s<\/p>\n

Hit Variable breakpoint on ‘C:\\fso\\BadScript.ps1:$num’ (Read access)<\/p>\n

 At C:\\fso\\BadScript.ps1:44 char:1<\/span><\/p>\n

+ SubOne($num) | DivideNum($num)<\/p>\n

+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<\/p>\n

[DBG]: PS C:\\>> s<\/p>\n

At C:\\fso\\BadScript.ps1:22 char:1<\/p>\n

+ {<\/p>\n

+ ~<\/p>\n

[DBG]: PS C:\\>> s<\/p>\n

At C:\\fso\\BadScript.ps1:23 char:2<\/p>\n

+  $num-1<\/p>\n

+  ~~~~~~<\/p>\n

[DBG]: PS C:\\>>\nIf you set the ReadWrite<\/b> access mode for the -mode<\/b> parameter for the variable $num<\/b> for the BadScript.ps1 script, you receive this feedback: <\/p>\n

PS C:\\> Set-PSBreakpoint -Variable num -Mode ReadWrite -Script C:\\FSO\\BadScript.ps1<\/p>\n

  ID Script            Line Command           Variable         Action
  — ——            —- ——-           ——–         ——
   6 BadScript.ps1                            num\nWhen you run the script (assuming you have disabled the other breakpoints), you will hit a breakpoint each time the $num<\/b> variable is read or written to. If you get tired of typing s<\/b> and pressing ENTER while you are in the debugging session, you can press ENTER, and it will repeat your previous s<\/b> command as you continue to step through the breakpoints.\nWhen the script has stepped through the code and arrives at the error in the BadScript.ps1 script, type q to exit the debugger. This is shown here:<\/p>\n

PS C:\\> C:\\fso\\BadScript.ps1
Hit Variable breakpoint on ‘C:\\fso\\BadScript.ps1:$num’ (ReadWrite access)<\/p>\n

At C:\\fso\\BadScript.ps1:43 char:1
+ $num = 0
+ ~~~~~~~~
[DBG]: PS C:\\>> s
At C:\\fso\\BadScript.ps1:44 char:1
+ SubOne($num) | DivideNum($num)
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\\>> s
Hit Variable breakpoint on ‘C:\\fso\\BadScript.ps1:$num’ (ReadWrite access)<\/p>\n

At C:\\fso\\BadScript.ps1:44 char:1
+ SubOne($num) | DivideNum($num)
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\\>> s
Hit Variable breakpoint on ‘C:\\fso\\BadScript.ps1:$num’ (ReadWrite access)<\/p>\n

At C:\\fso\\BadScript.ps1:44 char:1
+ SubOne($num) | DivideNum($num)
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\\>> s
At C:\\fso\\BadScript.ps1:22 char:1
+ {
+ ~
[DBG]: PS C:\\>> q
PS C:\\>\nWhen you use the ReadWrite<\/b> access mode of the -mode<\/b> parameter for breaking on variables, the breakpoint does not tell you if the operation is a Read operation or a Write operation. You have to look at the code that is being executed to determine if the value of the variable is being written or read.\nBy specifying a value for the -action<\/b> parameter, you can include regular Windows PowerShell code that will execute when the breakpoint is hit. If, for example, you are trying to follow the value of a variable within the script and you want to display the value of the variable each time the breakpoint is hit, you might want to specify an action that uses the Write-Host<\/b> cmdlet to display the value of the variable.\nBy using the Write-Host<\/b> cmdlet, you can also include a string that indicates that the value of the variable that is being displayed. This is crucial for picking up variables that never initialize; and therefore, it is easier to see than a blank line that would be displayed if you attempted to display the value of an empty variable. The technique of using the Write-Host<\/b> cmdlet in an -action<\/b> parameter is shown here:<\/p>\n

PS C:\\> Set-PSBreakpoint -Variable num -Action { write-host “num = $num” ;
Break } -Mode readwrite -script C:\\FSO\\BadScript.ps1<\/p>\n

  ID Script            Line Command           Variable         Action
  — ——            —- ——-           ——–         ——
   5 BadScript.ps1                            num               write-host “…\nWhen you run the C:\\FSO\\BadScript.ps1 with the breakpoint set, you receive the following output inside the Windows PowerShell debugger:<\/p>\n

PS C:\\> C:\\fso\\BadScript.ps1
num = 0
Hit Variable breakpoint on ‘C:\\FSO\\BadScript.ps1:$num’ (ReadWrite access)<\/p>\n

At C:\\fso\\BadScript.ps1:43 char:1
+ $num = 0
+ ~~~~~~~~
[DBG]: PS C:\\>> s
At C:\\fso\\BadScript.ps1:44 char:1
+ SubOne($num) | DivideNum($num)
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\\>> s
num = 0
Hit Variable breakpoint on ‘C:\\FSO\\BadScript.ps1:$num’ (ReadWrite access)<\/p>\n

At C:\\fso\\BadScript.ps1:44 char:1
+ SubOne($num) | DivideNum($num)
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\\>> c
num = 0
Hit Variable breakpoint on ‘C:\\FSO\\BadScript.ps1:$num’ (ReadWrite access)<\/p>\n

At C:\\fso\\BadScript.ps1:44 char:1
+ SubOne($num) | DivideNum($num)
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\\>> q
PS C:\\>\nThat is all there is to using variable breakpoints with the Windows PowerShell debugger. Debugging Week will continue tomorrow when I will talk about more cool stuff.\nI invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.\nEd Wilson, Microsoft Scripting Guy<\/b><\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Ed Wilson, Microsoft Scripting Guy, talks about using variable breakpoints with the Windows PowerShell debugger. Hello Windows PowerShell scripting dudes and dudettes! Debugging Week continues, and today I am talking about using variable breakpoints with the Windows PowerShell debugger. Setting a breakpoint on line 1 of the script is useful for easily entering a […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[294,3,4,45],"class_list":["post-72102","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-debugging","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Ed Wilson, Microsoft Scripting Guy, talks about using variable breakpoints with the Windows PowerShell debugger. Hello Windows PowerShell scripting dudes and dudettes! Debugging Week continues, and today I am talking about using variable breakpoints with the Windows PowerShell debugger. Setting a breakpoint on line 1 of the script is useful for easily entering a […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/72102","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=72102"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/72102\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=72102"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=72102"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=72102"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}