TOPIC about_Debuggers SHORT DESCRIPTION Describes the Windows PowerShell debugger. LONG DESCRIPTION Debugging is the process of examining a script while it is running in order to identify and correct errors in the script instructions. The Windows PowerShell debugger is designed to help you examine and identify errors and inefficiencies in your scripts. Note: The Windows PowerShell debugger does not run remotely. To debug a script on a remote computer, copy the script to the local computer. You can use the features of the Windows PowerShell debugger to examine a Windows PowerShell script, function, command, or expression while it is running. The Windows PowerShell debugger includes a set of cmdlets that let you set breakpoints, manage breakpoints, and view the call stack. Windows PowerShell offers several methods that you can use to debug scripts, functions, and commands. Method 1: The Set-PsDebug cmdlet offers basic script debugging features, including stepping and tracing. For more information, type: "get-help set-psdebug". Method 2: Use the Set-StrictMode cmdlet to detect references to uninitialized variables, to references to non-existent properties of an object, and to function syntax that is not valid. Method 3: Add diagnostic statements to a script, such as statements that display the value of variables, statements that read input from the command line, or statements that report the current instruction. Use the cmdlets that contain the Write verb for this task, such as Write-Host, Write-Debug, Write-Warning, and Write-Verbose. Method 4: Use the Windows PowerShell debugger to debug a script. Or, use the debugger to debug a function or script block that you typed at the command prompt. You can set breakpoints, step through the script, examine the values of variables, run diagnostics and logging commands, and display the call stack. Debugger Cmdlets The Windows PowerShell debugger includes the following set of cmdlets: Set-PsBreakpoint: Sets breakpoints on lines, variables, and commands. Get-PsBreakpoint: Gets breakpoints in the current session. Disable-PsBreakpoint: Turns off breakpoints in the current session. Enable-PsBreakpoint: Re-enables breakpoints in the current session. Remove-PsBreakpoint: Deletes breakpoints from the current session. Get-PsCallStack: Displays the current call stack. Starting and Stopping the Debugger To start the debugger, set one or more breakpoints. Then, run the script, command, or function that you want to debug. When you reach a breakpoint, execution stops, and control is turned over to the debugger. To stop the debugger, run the script, command, or function until it is complete. Or, type "stop" or "t". Debugger Commands When you use the debugger in the Windows PowerShell console, use the following commands to control the execution. Note: For information about how to use the debugger in other host applications, see the host application documentation. s, Step-into Executes the next statement and then stops. v, Step-over Executes the next statement, but skips functions and invocations. The skipped statements are executed, but not stepped through. o, Step-out Steps out of the current function; up one level 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. c, Continue Continues to run until the script is complete or until the next breakpoint is reached. The skipped statements are executed, but not stepped through. l, List Displays the part of the script that is executing. By default, it displays the current line, five previous lines, and 10 subsequent lines. To continue listing the script, press ENTER. l <m>, List Displays 16 lines of the script beginning with the line number specified by <m>. l <m> <n>, List Displays <n> lines of the script, beginning with the line number specified by <m>. q, Stop Stops executing the script, and exits the debugger. k, Get-PsCallStack Displays the current call stack. <Enter> Repeats the last command if it was Step (s), Step-over (v), or List (l). Otherwise, represents a submit action. ?, h Displays the debugger command Help. To exit the debugger, use Stop (q). While in the debugger, you can also enter commands, display the value of variables, use cmdlets, and run scripts. By using these debugger commands, you can run a script, stop on a point of concern, examine the values of variables and the state of the system, and continue running the script until you have identified a problem. The Debugger Environment When you reach a breakpoint, you enter the debugger environment. The command prompt changes so that it begins with "[DBG]:". You can customize the prompt. Also, in some host applications, such as the Windows PowerShell console, (but not in Windows PowerShell Integrated Scripting Environment [ISE]), a nested prompt opens for debugging. You can detect the nested prompt by the repeating greater-than characters (ASCII 62) that appear at the command prompt. For example, the following is the default debugging prompt in the Windows PowerShell console: [DBG]: PS (get-location)>>> You can find the nesting level by using the $NestedPromptLevel automatic variable. Additionally, an automatic variable, $PSDebugContext, is defined in the local scope. You can use the presence of the $PsDebugContext variable to determine whether you are in the debugger. For example: if ($psdebugcontext) {"Debugging"} else {"Not Debugging"} You can use the value of the $PSDebugContext variable in your debugging. [DBG]: PS>>> $psdebugcontext.invocationinfo Name CommandLineParameters UnboundArguments Location ---- --------------------- ---------------- -------- = {} {} C:\ps-test\vote.ps1 (1) Debugging and Scope Breaking into the debugger does not change the scope in which you are operating, but when you reach a breakpoint in a script, you move into the script scope. The script scope is a child of the scope in which you ran the debugger. To find the variables and aliases that are defined in the script scope, use the Scope parameter of the Get-Alias or Get-Variable cmdlets. For example, the following command gets the variables in the local (script) scope: get-variable -scope 0 You can abbreviate the command as: gv -s 0 This is a useful way to see only the variables that you defined in the script and that you defined while debugging. Debugging at the Command Line When you set a variable breakpoint or a command breakpoint, you can set the breakpoint only in a script file. However, by default, the breakpoint is set on anything that runs in the current session. For example, if you set a breakpoint on the $name variable, the debugger breaks on any $name variable in any script, command, function, script cmdlet or expression that you run until you disable or remove the breakpoint. This allows you to debug your scripts in a more realistic context in which they might be affected by functions, variables, and other scripts in the session and in the user's profile. Line breakpoints are specific to script files, so they are set only in script files. Debugging Functions When you set a breakpoint on a function that has Begin, Process, and End sections, the debugger breaks at the first line of each section. For example: function test-cmdlet { begin { write-output "Begin" } process { write-output "Process" } end { write-output "End" } } C:\PS> set-psbreakpoint -command test-cmdlet C:\PS> test-cmdlet Begin Entering debug mode. Use h or ? for help. ...
magdula294