# PR Summary * Replace an ordered list with sections * Fix an ordered list to continue numbering in each item ## PR Context <!-- Provide a little reasoning as to why this Pull Request helps and why you have opened it. --> ## PR Checklist - [x] [PR has a meaningful title](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md#pull-request---submission) - Use the present tense and imperative mood when describing your changes - [x] [Summarized changes](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md#pull-request---submission) - [x] [Make sure all `.h`, `.cpp`, `.cs`, `.ps1` and `.psm1` files have the correct copyright header](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md#pull-request---submission) - [x] This PR is ready to merge and is not [Work in Progress](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md#pull-request---work-in-progress). - If the PR is work in progress, please add the prefix `WIP:` or `[ WIP ]` to the beginning of the title (the `WIP` bot will keep its status check at `Pending` while the prefix is present) and remove the prefix when the PR is ready. - **[Breaking changes](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md#making-breaking-changes)** - [x] None - **OR** - [ ] [Experimental feature(s) needed](https://github.com/MicrosoftDocs/PowerShell-Docs/blob/staging/reference/6/Microsoft.PowerShell.Core/About/about_Experimental_Features.md) - [ ] Experimental feature name(s): <!-- Experimental feature name(s) here --> - **User-facing changes** - [x] Not Applicable - **OR** - [ ] [Documentation needed](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md#pull-request---submission) - [ ] Issue filed: <!-- Number/link of that issue here --> - **Testing - New and feature** - [x] N/A or can only be tested interactively - **OR** - [ ] [Make sure you've added a new test if existing tests do not effectively test the code changed](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md#before-submitting) - **Tooling** - [x] I have considered the user experience from a tooling perspective and don't believe tooling will be impacted. - **OR** - [ ] I have considered the user experience from a tooling perspective and enumerated concerns in the summary. This may include: - Impact on [PowerShell Editor Services](https://github.com/PowerShell/PowerShellEditorServices) which is used in the [PowerShell extension](https://github.com/PowerShell/vscode-powershell) for VSCode (which runs in a different PS Host). - Impact on Completions (both in the console and in editors) - one of PowerShell's most powerful features. - Impact on [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) (which provides linting & formatting in the editor extensions). - Impact on [EditorSyntax](https://github.com/PowerShell/EditorSyntax) (which provides syntax highlighting with in VSCode, GitHub, and many other editors).
5.7 KiB
Debugging in PowerShell Command-line
As we know, we can debug PowerShell code via GUI tools like Visual Studio Code. In addition, we can directly perform debugging within the PowerShell command-line session by using the PowerShell debugger cmdlets. This document demonstrates how to use the cmdlets for the PowerShell command-line debugging. We will cover the following topics: setting a debug breakpoint on a line of code and on a variable.
Let's use the following code snippet as our sample script.
# Convert Fahrenheit to Celsius
function ConvertFahrenheitToCelsius([double] $fahrenheit)
{
$celsius = $fahrenheit - 32
$celsius = $celsius / 1.8
$celsius
}
$fahrenheit = Read-Host 'Input a temperature in Fahrenheit'
$result =[int](ConvertFahrenheitToCelsius($fahrenheit))
Write-Host "$result Celsius"
Setting a Breakpoint on a Line
- Open a PowerShell editor
- Save the above code snippet to a file. For example, "test.ps1"
- Go to your command-line PowerShell
- Clear existing breakpoints if any
PS /home/jen/debug>Get-PSBreakpoint | Remove-PSBreakpoint
- Use Set-PSBreakpoint cmdlet to set a debug breakpoint. In this case, we will set it to line 5
PS /home/jen/debug>Set-PSBreakpoint -Line 5 -Script ./test.ps1
ID Script Line Command Variable Action
-- ------ ---- ------- -------- ------
0 test.ps1 5
- Run the script "test.ps1". As we have set a breakpoint, it is expected the program will break into the debugger at the line 5.
PS /home/jen/debug> ./test.ps1
Input a temperature in Fahrenheit: 80
Hit Line breakpoint on '/home/jen/debug/test.ps1:5'
At /home/jen/debug/test.ps1:5 char:1
+ $celsius = $celsius / 1.8
+ ~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS /home/jen/debug>>
- The PowerShell prompt now has the prefix [DBG]: as you may have noticed. This means we have entered into the debug mode. To watch the variables like $celsius, simply type $celsius as below.
- To exit from the debugging, type q
- To get help for the debugging commands, simply type ?. The following is an example of debugging output.
[DBG]: PS /home/jen/debug>> $celsius
48
[DBG]: PS /home/jen/debug>> $fahrenheit
80
[DBG]: PS /home/jen/debug>> ?
s, stepInto Single step (step into functions, scripts, etc.)
v, stepOver Step to next statement (step over functions, scripts, etc.)
o, stepOut Step out of the current function, script, etc.
c, continue Continue operation
q, quit Stop operation and exit the debugger
d, detach Continue operation and detach the debugger.
k, Get-PSCallStack Display call stack
l, list List source code for the current script.
Use "list" to start from the current line, "list <m>"
to start from line <m>, and "list <m> <n>" to list <n>
lines starting from line <m>
<enter> Repeat last command if it was stepInto, stepOver or list
?, h displays this help message.
For instructions about how to customize your debugger prompt, type "help about_prompt".
[DBG]: PS /home/jen/debug>> s
At PS /home/jen/debug/test.ps1:6 char:1
+ $celsius
+ ~~~~~~~~
[DBG]: PS /home/jen/debug>> $celsius
26.6666666666667
[DBG]: PS /home/jen/debug>> $fahrenheit
80
[DBG]: PS /home/jen/debug>> q
PS /home/jen/debug>
Setting a Breakpoint on a Variable
- Clear existing breakpoints if there are any
PS /home/jen/debug>Get-PSBreakpoint | Remove-PSBreakpoint
- Use Set-PSBreakpoint cmdlet to set a debug breakpoint. In this case, we set it to line 5
PS /home/jen/debug>Set-PSBreakpoint -Variable "celsius" -Mode write -Script ./test.ps1
-
Run the script "test.ps1"
Once hit the debug breakpoint, we can type l to list the source code that debugger is currently executing. As we can see line 3 has an asterisk at the front, meaning that's the line the program is currently executing and broke into the debugger as illustrated below.
-
Type q to exit from the debugging mode. The following is an example of debugging output.
./test.ps1
Input a temperature in Fahrenheit: 80
Hit Variable breakpoint on '/home/jen/debug/test.ps1:$celsius' (Write access)
At /home/jen/debug/test.ps1:3 char:1
+ $celsius = $fahrenheit - 32
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS /home/jen/debug>> l
1: function ConvertFahrenheitToCelsius([double] $fahrenheit)
2: {
3:* $celsius = $fahrenheit - 32
4: $celsius = $celsius / 1.8
5: $celsius
6: }
7:
8: $fahrenheit = Read-Host 'Input a temperature in Fahrenheit'
9: $result =[int](ConvertFahrenheitToCelsius($fahrenheit))
10: Write-Host "$result Celsius"
[DBG]: PS /home/jen/debug>> $celsius
48
[DBG]: PS /home/jen/debug>> v
At /home/jen/debug/test.ps1:4 char:1
+ $celsius = $celsius / 1.8
+ ~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS /home/jen/debug>> v
Hit Variable breakpoint on '/home/jen/debug/test.ps1:$celsius' (Write access)
At /home/jen/debug/test.ps1:4 char:1
+ $celsius = $celsius / 1.8
+ ~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS /home/jen/debug>> $celsius
26.6666666666667
[DBG]: PS /home/jen/debug>> q
PS /home/jen/debug>
Now you know the basics of the PowerShell debugging from PowerShell command-line. For further learning, read the following articles.