Merge pull request #1349 from PowerShell/jianyun/docs

Added Debugging from PS Commandline

docs/learning-powerShell/debugging-from-commandline.md

@@ -0,0 +1,173 @@
+Debugging in PowerShell Command-line
+=====
+
+As we know we can debug PowerShell code via GUI tools like [VS Code](./using-vscode.md#debugging-with-vs-code) or [ISE](./using-ise.md#debugging-with-ise). 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 two topics: set 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. Set a Breakpoint on a Line**
+
+- Open a [PowerShell editor](learning-powershell.md#powershell-editor)
+- Save the above code snippet to a file, let's say "test.ps1"
+- Clear existing breakpoints if any
+
+```PowerShell
+ Get-PSBreakpoint | Remove-PSBreakpoint
+ ```
+- Use **Set-PSBreakpoint** cmdlet to set a debug breakpoint, say set it to line 5
+
+```PowerShell
+PS C:\Test>Set-PSBreakpoint -Line 5 -Script .\test.ps1
+
+ID Script             Line       Command          Variable          Action
+-- ------             ----       -------          --------          ------
+ 5 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 C:\Test> .\test.ps1
+Input a temperature in Fahrenheit: 80
+Hit Line breakpoint on 'C:\Test\test.ps1:5'
+
+At C:\Test\test.ps1:5 char:1
++ $celsius = $celsius / 1.8
++ ~~~~~~~~~~~~~~~~~~~~~~~~~
+[DBG]: PS C:\Test>>
+```
+
+- The PowerShell prompt has been changed to **[DBG]: PS C:\Test>>** as you may 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, simple type **"?"**
+
+```PowerShell
+[DBG]: PS C:\Test>> $celsius
+48
+[DBG]: PS C:\Test>> $fahrenheit
+80
+[DBG]: PS PS C:\Test>> ?
+
+ 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 C:\Test>> s
+At C:\Test\test.ps1:6 char:1
++ $celsius
++ ~~~~~~~~
+[DBG]: PS C:\Test>> $celsius
+26.6666666666667
+[DBG]: PS C:\Test>> $fahrenheit
+80
+
+[DBG]: PS C:\Test>> q
+PS C:\Test>
+
+```
+
+
+**2. Set a Breakpoint on a Variable**
+- Clear existing breakpoints if any
+
+```PowerShell
+ PS C:\Test>Get-PSBreakpoint | Remove-PSBreakpoint
+ ```
+- Use **Set-PSBreakpoint** cmdlet to set a debug breakpoint, say set it to line 5
+
+```PowerShell
+
+ PS C:\Test>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
+
+```PowerShell
+
+PS C:\Test> .\test.ps1
+Input a temperature in Fahrenheit: 80
+Hit Variable breakpoint on 'C:\Test\test.ps1:$celsius' (Write access)
+
+At C:\Test\test.ps1:3 char:1
++ $celsius = $fahrenheit - 32
++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[DBG]: PS C:\Test>> 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 C:\Test>> $celsius
+48
+[DBG]: PS C:\Test>> v
+At C:\Test\test.ps1:4 char:1
++ $celsius = $celsius / 1.8
++ ~~~~~~~~~~~~~~~~~~~~~~~~~
+[DBG]: PS C:\Test>> v
+Hit Variable breakpoint on 'C:\Test\test.ps1:$celsius' (Write access)
+
+At C:\Test\test.ps1:4 char:1
++ $celsius = $celsius / 1.8
++ ~~~~~~~~~~~~~~~~~~~~~~~~~
+[DBG]: PS C:\Test>> $celsius
+26.6666666666667
+[DBG]: PS C:\Test>> q
+PS C:\Test>
+
+```
+
+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/)

docs/learning-powerShell/learning-powershell.md

@@ -47,11 +47,14 @@ PowerShell Debugger
 Assuming you have written a PowerShell script which may contains a software bug, you would like to fix the issue via debugging. As an example, we use VS Code. Click on the link below to start debugging:
 
 - [Using Visual Studio Code (VS Code)][use-vscode-debugger]
+- [PowerShell Command-line Debugging][cli-debugging]
 
 On Windows, you can also use  [ISE][use-ise-debugger] to debug PowerShell scripts.
 
 [use-vscode-debugger]:./using-vscode.md#debugging-with-vs-code
 [use-ise-debugger]:./using-ise.md#debugging-with-ise
+[cli-debugging]:./debugging-from-commandline.md
+
 
 PowerShell Testing
 ----
@@ -82,7 +85,7 @@ More Reading
 - [Introduction to PowerShell][powershell-intro] from Pluralsight
 - PowerShell Web Docs: [Basic cookbooks][basic-cookbooks]
 - [PowerShell eBooks][ebooks-from-powershell.com] from PowerShell.com
-- [PowerShell Training and tutorials][lynda-training] from Lynda.com
+- [PowerShell Training and Tutorials][lynda-training] from Lynda.com
 - [Learn PowerShell][channel9-learn-powershell] from channel9
 - [Learn PowerShell Video Library][powershell.com-learn-powershell] from PowerShell.com
 - [PowerShell Quick Reference][quick-reference] by PowerShellMagazine.com

docs/learning-powerShell/powershell-beginners-guide.md

@@ -6,7 +6,7 @@ If you are new to PowerShell, this document will walk you through a few examples
 
 Launch PowerShell Console/Session
 ---
-Follow the [Installing PowerShell](./learning-powershell.md "Installing PowerShell") instruction you can install the PowerShell and launch the PowerShell session.
+First you need to launch a PowerShell session by following the [Installing PowerShell Guide](./learning-powershell.md#installing-powershell).
 
 
 Getting Familiar with PowerShell Commands

docs/learning-powerShell/using-ise.md

@@ -14,9 +14,9 @@ Editing with ISE
 # Convert Fahrenheit to Celsius
 function ConvertFahrenheitToCelsius([double] $fahrenheit)
 {
-$celcius = $fahrenheit - 32
-$celcius = $celcius / 1.8
-$celcius
+$celsius = $fahrenheit - 32
+$celsius = $celsius / 1.8
+$celsius
 }
 
 $fahrenheit = Read-Host 'Input a temperature in Fahrenheit'
@@ -52,10 +52,10 @@ Hit Line breakpoint on 'C:\test\helloword.ps1:17'
 
 ```
 
-- From the output pane, you can type $celcius and $fahrenheit to exam these variables to see if they are correct.
+- From the output pane, you can type $celsius and $fahrenheit to exam the values of these variables to see if they are correct.
 
 ```PowerShell
-[DBG]: PS C:\Test>> $celcius
+[DBG]: PS C:\Test>> $celsius
 26.6666666666667
 
 [DBG]: PS C:\Tset>> $fahrenheit

docs/learning-powerShell/using-vscode.md

@@ -5,7 +5,7 @@ If you are working on Linux and OS X, you cannot use ISE because it is not suppo
 
 You can use VS Code on Windows with PowerShell V5 by using Windows 10 or by installing [Windows Management Framework 5.0 RTM](https://www.microsoft.com/en-us/download/details.aspx?id=50395) for down-level Windows OSs.
 
-Before starting it, please make sure PowerShell exists on your system. Follow the [Installing PowerShell](./learning-powershell.md "Installing PowerShell") instruction you can install the PowerShell and launch the PowerShell session.
+Before starting it, please make sure PowerShell exists on your system. Follow the [Installing PowerShell](./learning-powershell.md#installing-powershell) instruction you can install the PowerShell and launch the PowerShell session.
 
 Editing with VS Code
 ----
@@ -35,7 +35,8 @@ Editing with VS Code
 
 -	After the install, you will see the **Install** button turns to **Enable**.
 -	Click on Enable and OK
--	Now you are ready for editing.
+-	Now you are ready for editing. for example, to create a new file, click File->New; to save it, click File->Save and then provide
+ a file name, let's say "helloworld.ps1"; to close the file, click on "x"; to exit the VS Code, File->Exit.
 
 
 Debugging with VS Code
@@ -72,10 +73,10 @@ Debugging with VS Code
     ]
 }
 ```
--	Once the debug configuration is established, now go to your helloworld.ps1 and set a breakpoint by pressing **F9**.
+-	Once the debug configuration is established, now go to your helloworld.ps1 and set a breakpoint by pressing **F9** on a line you wish to debug break into.
+-	To disable the breakpoint, press **F9** again.
 -	Press **F5** to let the run.
 
-
 There are a few blogs that may be helpful to get you started using PowerShell extension for VS Code
 
 -	Visual Studio Code: [PowerShell Extension][ps-extension]