a8efa49dbf
This change updates the "Using Visual Studio Code" documentation to give guidance on how to configure VS Code on to use a specific installation of PowerShell.
175 lines
5.7 KiB
Markdown
175 lines
5.7 KiB
Markdown
Debugging in PowerShell Command-line
|
|
=====
|
|
|
|
As we know, we can debug PowerShell code via GUI tools like [Visual Studio Code](./using-vscode.md#debugging-with-vs-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.
|
|
|
|
```PowerShell
|
|
# 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"
|
|
|
|
```
|
|
|
|
|
|
**1. Setting a Breakpoint on a Line**
|
|
|
|
- Open a [PowerShell editor](README.md#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
|
|
|
|
```PowerShell
|
|
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
|
|
|
|
```PowerShell
|
|
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.
|
|
|
|
```PowerShell
|
|
|
|
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.
|
|
|
|
```PowerShell
|
|
[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>
|
|
|
|
```
|
|
|
|
|
|
**2. Setting a Breakpoint on a Variable**
|
|
- Clear existing breakpoints if there are any
|
|
|
|
```PowerShell
|
|
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
|
|
|
|
```PowerShell
|
|
|
|
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.
|
|
|
|
```PowerShell
|
|
|
|
PS /home/jen/debug> ./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.
|
|
|
|
|
|
More Reading
|
|
=====
|
|
- [about_Debuggers](https://technet.microsoft.com/en-us/library/hh847790.aspx)
|
|
- [PowerShell Debugging](https://blogs.technet.microsoft.com/heyscriptingguy/tag/debugging/)
|