{"id":72082,"date":"2015-07-18T00:01:00","date_gmt":"2015-07-18T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2015\/07\/18\/weekend-scripter-break-in-to-a-script-via-a-command\/"},"modified":"2019-02-18T09:46:57","modified_gmt":"2019-02-18T16:46:57","slug":"weekend-scripter-break-in-to-a-script-via-a-command","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/weekend-scripter-break-in-to-a-script-via-a-command\/","title":{"rendered":"Weekend Scripter: Break in to a Script via a Command"},"content":{"rendered":"

Summary<\/b>: Ed Wilson, Microsoft Scripting Guy, talks about using the debugger to break in to a script via a specific command.<\/span>\nMicrosoft Scripting Guy, Ed Wilson, is here. One of the cool things, when troubleshooting a specific function in Windows PowerShell, is to set a breakpoint to occur each time the command is called. Remember, Windows PowerShell functions are also Windows PowerShell commands, just as language statements and cmdlets are.<\/p>\n

To set the breakpoint in a command, you use the -command<\/b> parameter. You can break on a call to a Windows PowerShell cmdlet, function, or external script. You can use aliases when setting breakpoints. When you create a breakpoint on an alias for a cmdlet, the debugger will only stop on the use of the alias—not on the actual command name.<\/p>\n

In addition, you do not have to specify a script for the debugger to break. If you do not type a path to a script, the debugger will be active for everything within the Windows PowerShell console session. Every occurrence of the Foreach<\/b> command will cause the debugger to break. The command to set such a breakpoint is shown here:<\/p>\n

Set-PSBreakpoint -Command Foreach<\/p>\n

Because Foreach<\/b> is a language statement in addition to an alias for the Foreach-Object<\/b> cmdlet, you might wonder whether the Windows PowerShell debugger will break on the language statement and on the use of the alias for the cmdlet. The answer is no.<\/p>\n

You can set breakpoints on language statements, but the debugger will not break on a language statement. As shown here, the debugger breaks on the use of the Foreach<\/b> alias, but not on the use of the Foreach-Object<\/b> cmdlet or the %<\/b> alias:<\/p>\n

PS C:\\> 1..3 | Foreach-Object {$_}
1
2
3
PS C:\\> 1..3 | % {$_}
1
2
3
PS C:\\> 1..3 | foreach {$_}
Hit Command breakpoint on ‘foreach’<\/p>\n

At line:1 char:1
+ 1..3 | foreach {$_}
+ ~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\\>> c
1
2
3
PS C:\\><\/p>\n

Note<\/b> You can use the shortcut technique of creating the breakpoint for the Windows PowerShell session and not specifically for the script. By leaving out the -script<\/b> parameter when creating a breakpoint, you cause the debugger to break in to any running script that uses the named function. This allows you to use the same breakpoints when debugging scripts that use the same function.<\/p>\n

When creating a breakpoint for the DivideNum<\/b> function that is used in the C:\\FSO\\BadScript.ps1 script, you can leave off the path to the script, because only this script uses the DivideNum<\/b> function.<\/p>\n

This makes the command easier to type, but it could become confusing if you’re looking through a collection of breakpoints. If you are debugging multiple scripts in a single Windows PowerShell console session, it could become confusing if you do not specify the script to which the breakpoint applies—unless, of course, you are specifically debugging the function as it is used in multiple scripts.<\/p>\n

Creating a command breakpoint for the DivideNum<\/b> function is shown here:<\/p>\n

PS C:\\> Set-PSBreakpoint -Command DivideNum<\/p>\n

  ID Script            Line Command           Variable         Action
  — ——            —-       ——-                ——–            ——
   7                        DivideNum\nWhen you run the script, it hits a breakpoint when the DivideNum<\/b> function is called. When BadScript.ps1 hits the DivideNum<\/b> function, the value of $num<\/b> is 0. As you step through the DivideNum<\/b> function, you assign a value of 2 to the $num<\/b> variable, a result of 6 is displayed, and then the 12\/$num<\/b> operation is carried out.\nNext, the AddOne<\/b> function is called and the value of $num<\/b> once again becomes 0. When the AddTwo<\/b> function is called, the value of $num<\/b> also becomes 0. This is shown here:<\/p>\n

PS C:\\> C:\\fso\\BadScript.ps1
Hit Command breakpoint on ‘DivideNum’<\/p>\n

At C:\\fso\\BadScript.ps1:37 char:1
+ {
+ ~
[DBG]: PS C:\\>> s
At C:\\fso\\BadScript.ps1:38 char:2
+  12\/$num
+  ~~~~~~~
[DBG]: PS C:\\>> $num
0
[DBG]: PS C:\\>> $num=2
[DBG]: PS C:\\>> s
6
At C:\\fso\\BadScript.ps1:39 char:1
+ } #end function DivideNum
+ ~
[DBG]: PS C:\\>> s
At C:\\fso\\BadScript.ps1:45 char:1
+ AddOne($num) | AddTwo($num)
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\\>> $num
0
[DBG]: PS C:\\>> s
At C:\\fso\\BadScript.ps1:12 char:1
+ {
+ ~
[DBG]: PS C:\\>> q
PS C:\\><\/p>\n

Responding to breakpoints<\/h2>\n

When the script reaches a breakpoint, control of the Windows PowerShell console is turned over to you. Inside the debugger, you can type any legal Windows PowerShell command, and even run cmdlets such as Get-Process<\/b> or Get-Service<\/b>.<\/p>\n

In addition, there are several new debugging commands that can be typed into the Windows PowerShell console when a breakpoint has been reached. The available debug commands are shown in the following table.<\/p>\n

Windows PowerShell debugging commands<\/h4>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
\n

Keyboard shortcut<\/b><\/p>\n<\/td>\n

\n

Command name<\/b><\/p>\n<\/td>\n

\n

Command meaning<\/b><\/p>\n<\/td>\n<\/tr>\n

\n

S<\/p>\n<\/td>\n

\n

Step-Into<\/i><\/p>\n<\/td>\n

\n

Executes the next statement and then stops.<\/p>\n<\/td>\n<\/tr>\n

\n

V<\/p>\n<\/td>\n

\n

Step-Over<\/i><\/p>\n<\/td>\n

\n

Executes the next statement, but skips functions and invocations. The skipped statements are executed, but not stepped through.<\/p>\n<\/td>\n<\/tr>\n

\n

O<\/p>\n<\/td>\n

\n

Step-Out<\/i><\/p>\n<\/td>\n

\n

Steps up one level in the current function, if nested. If in the main body, it continues to the end or the next breakpoint. The skipped statements are executed, but not stepped through.<\/p>\n<\/td>\n<\/tr>\n

\n

C<\/p>\n<\/td>\n

\n

Continue<\/i><\/p>\n<\/td>\n

\n

Continues to run until the script is complete or until the next breakpoint is reached. The skipped statements are executed, but not stepped through.<\/p>\n<\/td>\n<\/tr>\n

\n

L<\/p>\n<\/td>\n

\n

List<\/i><\/p>\n<\/td>\n

\n

Displays the part of the script that is executing. By default, it displays the current line, 5 previous lines, and 10 subsequent lines. To continue listing the script, press ENTER.<\/p>\n<\/td>\n<\/tr>\n

\n

L <M><\/p>\n<\/td>\n

\n

List<\/i><\/p>\n<\/td>\n

\n

Displays 16 lines of the script, beginning with the line number specified by M.<\/p>\n<\/td>\n<\/tr>\n

\n

L <M> <N><\/p>\n<\/td>\n

\n

List<\/i><\/p>\n<\/td>\n

\n

Displays the number of lines of the script specified by N, beginning with the line number specified by M.<\/p>\n<\/td>\n<\/tr>\n

\n

Q<\/p>\n<\/td>\n

\n

Stop (Quit)<\/i><\/p>\n<\/td>\n

\n

Stops executing the script and exits the debugger.<\/p>\n<\/td>\n<\/tr>\n

\n

K<\/p>\n<\/td>\n

\n

Get-PsCallStack<\/i><\/p>\n<\/td>\n

\n

Displays the current call stack.<\/p>\n<\/td>\n<\/tr>\n

\n

ENTER<\/p>\n<\/td>\n

\n

Repeat<\/i><\/p>\n<\/td>\n

\n

Repeats the last command if it was Step-Into<\/b>, Step-Over<\/b>, or List<\/b>. Otherwise, represents a submit action.<\/p>\n<\/td>\n<\/tr>\n

\n

H or ?<\/p>\n<\/td>\n

\n

Help<\/i><\/p>\n<\/td>\n

\n

Displays the debugger command Help.<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

That wraps up Debugging Week. I invite you to follow me on <\/span>Twitter<\/a> and <\/span>Facebook<\/a>. If you have any questions, send email to me at <\/span>scripter@microsoft.com<\/a>, or post your questions on the <\/span>Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/span><\/p>\n

Ed Wilson, Microsoft Scripting Guy<\/b> <\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Ed Wilson, Microsoft Scripting Guy, talks about using the debugger to break in to a script via a specific command. Microsoft Scripting Guy, Ed Wilson, is here. One of the cool things, when troubleshooting a specific function in Windows PowerShell, is to set a breakpoint to occur each time the command is called. Remember, […]<\/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":[602,3,4,61,45],"class_list":["post-72082","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-debugger","tag-scripting-guy","tag-scripting-techniques","tag-weekend-scripter","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Ed Wilson, Microsoft Scripting Guy, talks about using the debugger to break in to a script via a specific command. Microsoft Scripting Guy, Ed Wilson, is here. One of the cool things, when troubleshooting a specific function in Windows PowerShell, is to set a breakpoint to occur each time the command is called. Remember, […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/72082","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=72082"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/72082\/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=72082"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=72082"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=72082"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}