admin/PowerShell-PowerShell
1
0
Fork 0
mirror of https://github.com/PowerShell/PowerShell synced 2026-06-08 12:12:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1381 from PowerShell/jianyun/docs

Browse Source 
Removed Get-Help, -ls from the example in the beginner's guide.
This commit is contained in:
Jianyun
2016-07-15 10:12:21 -07:00
committed by GitHub
parent 24b78df64a da28473dd6
commit 7e8e8592e3
5 changed files with 90 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/learning-powerShell/debugging-from-commandline.md
+15 -15
View File
@@ -1,7 +1,7 @@
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.
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 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.
@@ -21,17 +21,17 @@ Write-Host "$result Celsius"
```
**1. Set a Breakpoint on a Line**
**1. Setting 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"
- 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, say set it to line 5
- 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
@@ -40,7 +40,7 @@ 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.
- 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
@@ -54,10 +54,10 @@ At /home/jen/debug/test.ps1:5 char:1
[DBG]: PS /home/jen/debug>>
```
- The PowerShell prompt has been changed to **[DBG]: PS /home/jen/debug>>** 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 **"?"**
- The PowerShell prompt now has the prefix **[DBG]:** 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, simply type **?**. The following is an example of debugging output.
```PowerShell
[DBG]: PS /home/jen/debug>> $celsius
@@ -103,13 +103,13 @@ PS /home/jen/debug>
```
**2. Set a Breakpoint on a Variable**
- Clear existing breakpoints if any
**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, say set it to line 5
- Use **Set-PSBreakpoint** cmdlet to set a debug breakpoint. In this case, we set it to line 5
```PowerShell
@@ -117,10 +117,10 @@ PS /home/jen/debug>
```
- Run the 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
- Type **q** to exit from the debugging mode. The following is an example of debugging output.
```PowerShell
@@ -165,7 +165,7 @@ PS /home/jen/debug>
```
Now you know the basics of the PowerShell debugging from PowerShell command-line. For further learning read the following articles.
Now you know the basics of the PowerShell debugging from PowerShell command-line. For further learning, read the following articles.
More Reading
docs/learning-powerShell/learning-powershell.md
+4 -4
View File
@@ -25,14 +25,14 @@ TODO: Raghu for setup-dev-environment.md
Getting Started with PowerShell
----
PowerShell command has a Verb-None structure with a set of parameters. It's easy to learn and use PowerShell. For example, "Get-Process" will display all the running processes on your system. Let's walk through with a few examples by clicking on the [PowerShell Beginner's Guide](powershell-beginners-guide.md).
PowerShell command has a Verb-Noun structure with a set of parameters. It's easy to learn and use PowerShell. For example, "Get-Process" will display all the running processes on your system. Let's walk through with a few examples by clicking on the [PowerShell Beginner's Guide](powershell-beginners-guide.md).
Now you have learned the basics of PowerShell. Please continue reading: Editor, Debugger, and Testing Tool if you want to do some development work in PowerShell.
Now you have learned the basics of PowerShell. Please continue reading if you want to do some development work in PowerShell.
PowerShell Editor
----
In this section, you will create a PowerShell script using PowerShell editor. You can certainly use your favorite editor to write scripts. As an example, we use Visual Studio Code (VS Code) which works for Windows, Linux, or OS X. Click on the following link to start create your first PowerShell script, let's say helloworld.ps1.
In this section, you will create a PowerShell script using PowerShell editor. You can use your favorite editor to write scripts. As an example, we will use Visual Studio Code (VS Code) which works for Windows, Linux, or OS X. Click on the following link to start create your first PowerShell script, let's say helloworld.ps1.
- [Using Visual Studio Code (VS Code)][use-vscode-editor]
@@ -44,7 +44,7 @@ On Windows, you can also use [PowerShell Integrated Scripting Environment (ISE)]
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:
Assuming you have written a PowerShell script which may contain a software bug, you can fix the issue via debugging. As an example, we will 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]
docs/learning-powerShell/powershell-beginners-guide.md
+44 -22
View File
@@ -11,11 +11,18 @@ First you need to launch a PowerShell session by following the [Installing Power
Getting Familiar with PowerShell Commands
---
In this section, you will learn how to
- create a file, delete a file and change file directory
- find syntax of PowerShell cmdlets
- get help if you needed
- discover what version of PowerShell you are currently using
- exit a PowerShell session
- and more
As mentioned above PowerShell commands is designed to have Verb-Noun structure, for instance Get-Process, Set-Location, Clear-Host, etc. Let’s exercise some of the basic PowerShell commands also known as **cmdlets**.
As mentioned above, PowerShell commands is designed to have Verb-Noun structure, for instance Get-Process, Set-Location, Clear-Host, etc. Let’s exercise some of the basic PowerShell commands, also known as **cmdlets**.
Please note that we will use the PowerShell prompt sign **PS />** in the following examples as it shows on Linux.
It looks like **PS C:\>** on Windows.
Please note that we will use the PowerShell prompt sign **PS />** as it appears on Linux in the following examples.
It is shown as **PS C:\\>** on Windows.
**1. Get-Process**: displays the processes running on your system.
@@ -88,7 +95,7 @@ PS /> cls
PS /> Set-Location /home
PS /home>
```
**5. ls or dir - Get-ChildItem**: list all items in the specified location
**5. dir - Get-ChildItem**: list all items in the specified location
```PowerShell
Get all files under the current directory:
@@ -119,10 +126,10 @@ Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 7/7/2016 7:17 PM 0 test.ps1
```
You can use the **-value** parameter to add some data to your file. For example, the following command adds the phrase "Write-Host 'Hello There'" as a file content to the test.ps1. Because the test.txt file exists already, we use **-force** parameter to replace the existing content.
You can use the **-Value** parameter to add some data to your file. For example, the following command adds the phrase "Write-Host 'Hello There'" as a file content to the test.ps1. Because the test.ps1 file exists already, we use **-Force** parameter to replace the existing content.
```PowerShell
PS /home/jen> New-Item -Path ./test.ps1 -Value "Write-Host 'hello there'" -force
PS /home/jen> New-Item -Path ./test.ps1 -Value "Write-Host 'hello there'" -Force
Directory: /home/jen
@@ -132,7 +139,7 @@ Mode LastWriteTime Length Name
-a---- 7/7/2016 7:19 PM 24 test.ps1
```
There are other ways to add some data to a file, for example, you can use Set-Content to set the file contents:
There are other ways to add some data to a file. For example, you can use Set-Content to set the file contents:
```PowerShell
PS /home/jen>Set-Content -Path ./test.ps1 -Value "Write-Host 'hello there again!'"
@@ -162,19 +169,34 @@ This cmdlet will delete the file /home/jen/test.ps1:
```PowerShell
PS /home/jen> Remove-Item ./test.ps1
```
**9. Exit**: - to exit the PowerShell session, type "exit"
**9. $PSVersionTable**: displays the version of PowerShell you are currently using
Type **$PSVersionTable** in your PowerShell session, you will see something like below. "PSVersion" indicates the
PowerShell version that you are using.
```PowerShell
Name Value
---- -----
PSVersion 5.1.10032.0
PSEdition Linux
PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...}
BuildVersion 3.0.0.0
CLRVersion
WSManStackVersion 1.0
PSRemotingProtocolVersion 2.3
SerializationVersion 1.1.0.1
```
**10. Exit**: to exit the PowerShell session, type "exit"
```PowerShell
PS /home/jen> exit
```
Need Help?
----
The most important command in PowerShell is possibly the Get-Help, which allows you to quickly learn PowerShell without having to surfing around the Internet. The Get-Help cmdlet also shows you how PowerShell commands work with examples.
PS />**Get-Help**
You can use this cmdlet to get help with any PowerShell commands.
The most important command in PowerShell is possibly the Get-Help, which allows you to quickly learn PowerShell without having to surf around the Internet. The Get-Help cmdlet also shows you how PowerShell commands work with examples.
PS />**Get-Help -Name Get-Process**
@@ -184,14 +206,14 @@ It shows the syntax and other technical information of the Get-Process cmdlet.
PS />**Get-Help -Name Get-Process -Examples**
It displays the examples how to use the Get-Process cmdlet.
If you use **-full** parameter, i.e., "Get-Help -Name Get-Process -Full", it will display more technical information.
If you use **-Full** parameter, i.e., "Get-Help -Name Get-Process -Full", it will display more technical information.
Discover All Commands Available on Your System
----
You want to discover what PowerShell cmdlets available on your system. Simple, just run "Get-Command" as below.
You want to discover what PowerShell cmdlets available on your system? Simple, just run "Get-Command" as below.
PS /> **Get-Command**
@@ -203,14 +225,14 @@ If you want to know the syntax of Get-Process cmdlet, type
PS /> **Get-Command Get-Process -Syntax**
If you want to know how to sue the get-process, type
If you want to know how to use the Get-Process, type
PS /> **Get-Help Get-Process -example**
PS /> **Get-Help Get-Process -Example**
PowerShell Pipeline '|'
----
Sometimes when you run Get-ChildItem or "dir", you want to get a list of files in a descending order. To archive that, type:
Sometimes when you run Get-ChildItem or "dir", you want to get a list of files in a descending order. To achieve that, type:
```PowerShell
PS /home/jen> dir | sort -Descending
```
@@ -229,10 +251,10 @@ Mode LastWriteTime Length Name
```
How to Create and Run PowerShell scripts
----
- You can use ISE, VS Code, or any favorite editor to create a PowerShell script and save the script with a .ps1 file extension (helloworld.ps1 in the example)
- To run the script, cd to your current folder and type ./helloworld.ps1
- You can use ISE, VS Code or your favorite editor to create a PowerShell script and save the script with a .ps1 file extension (for example, helloworld.ps1)
- To run the script, cd to your current folder and type ./yourscript.ps1 (for example, ./helloworld.ps1).
See [Running PowerShell Scripts Is as Easy as 1-2-3] [run-ps] for more details.
Note: if you are using Windows, make sure you set the PowerShell's execution policy to "RemoteSigned" in this case. See [Running PowerShell Scripts Is as Easy as 1-2-3] [run-ps] for more details.
[run-ps]:http://windowsitpro.com/powershell/running-powershell-scripts-easy-1-2-3
docs/learning-powerShell/using-ise.md
+13 -13
View File
@@ -1,14 +1,14 @@
Using PowerShell Integrated Scripting Environment (ISE)
====
The PowerShell ISE works on Windows. If you are not using Windows, please see [Using VS Code](./using-vscode.md).
The PowerShell ISE only works on Windows. If you are not using Windows, please see [Using VS Code](./using-vscode.md).
Editing with ISE
---
- Launch PowerShell ISE
* Press Windows Key -> type PowerShell ISE, click on PowerShell ISE to launch the ISE
* Press Windows Key -> type "PowerShell ISE", click on PowerShell ISE to launch the ISE
- Create a new PowerShell Script
* Click on File -> New
* Add a few lines of PowerShell scripts in your newly created file, for example,
* Click on **File->New**
* Add a few lines of PowerShell code in your newly created file. In this case, we will use the following script snippet.
```PowerShell
# Convert Fahrenheit to Celsius
@@ -25,21 +25,21 @@ Write-Host "$result Celsius"
```
* **Note**: You can find more examples [here](http://examples.oreilly.com/9780596528492/).
- Save the script file
* Click on File-> Save As -> type "helloworld.ps1"
- Close the helloworld.ps1
* File-> Close
- Reopen the helloworld.ps1
* File-> Open, then choose helloworld.ps1.
- To save the script file
* Click on **File->Save As**. Then type "helloworld.ps1"
- To close the helloworld.ps1 file
* **File->Close**
- To reopen the helloworld.ps1 file
* **File->Open**, then choose helloworld.ps1
- For more details, go to [How to Write and Run Scripts in the Windows PowerShell ISE](https://msdn.microsoft.com/en-us/powershell/scripting/core-powershell/ise/how-to-write-and-run-scripts-in-the-windows-powershell-ise).
Debugging with ISE
----
To execute the entire script file, you can press **F5**; to execute several lines of your scripts, simply select them and press **F8**. However sometimes you would like to stop the execution on a particular line in order to exam some variables to check if the program runs as expected. In that case, you may follow the steps below. Let's take the helloworld.ps1 as an example and assume line 17 is the place where you want to stop.
To execute the entire script file, you can press **F5**. To execute several lines of your scripts, simply select them and press **F8**. If you would like to stop the execution on a particular line in order to examine some variables to check if the program runs as expected. In that case, you may follow the steps below. Let's take the helloworld.ps1 as an example and assume line 17 is the place where you want to stop.
- Set a break point: Move mouse over on the line 17, and press **F9**. You will see the line 17 is highlighted which means a breakpoint gets set.
- Set a break point: Move mouse over on the line 17, and press **F9**. You will see the line 17 is highlighted, which means a breakpoint is set.
- Press **F5** to run the script
- Enter 80 (or any number in Fahrenheit) from the command line prompt
- Notice that the ISE output pane becomes “[DBG]: PS C:\Test>>” prompt. This means the program is in the debugging mode. It stops at Line 17:
@@ -52,7 +52,7 @@ Hit Line breakpoint on 'C:\test\helloword.ps1:17'
```
- From the output pane, you can type $celsius and $fahrenheit to exam the values of these variables to see if they are correct.
- From the output pane, you can type $celsius and $fahrenheit to examine the values of these variables to see if they are correct.
```PowerShell
[DBG]: PS C:\Test>> $celsius
docs/learning-powerShell/using-vscode.md
+14 -13
View File
@@ -1,11 +1,11 @@
Using Visual Studio Code (VS Code)
====
If you are working on Linux and OS X, you cannot use ISE because it is not supported on these platforms. In this case you can choose your favorite editor to write PowerShell scripts. Here we choose VS Code as a PowerShell editor as an example.
If you are working on Linux and OS X, you cannot use ISE because it is not supported on these platforms. In this case, you can choose your favorite editor to write PowerShell scripts. Here we choose VS Code as a PowerShell editor as an example.
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.
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 (e.g. Windows 8.1, etc.).
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. By following the [Installing PowerShell](./learning-powershell.md#installing-powershell) instructions you can install PowerShell and launch a PowerShell session.
Editing with VS Code
----
@@ -28,28 +28,28 @@ Editing with VS Code
- Press **F1** (or **Ctrl+Shift+P**) which opens up the “Command Palette” inside the VS Code app.
- In the command palette, type **ext install** and hit Enter. It will show all VS Code extensions available on your system.
- Choose PowerShell and click on Install, you will see something like below
- In the command palette, type **ext install** and hit **Enter**. It will show all VS Code extensions available on your system.
- Choose PowerShell and click on **Install**, you will see something like below
![VSCode](vscode.png)
- After the install, you will see the **Install** button turns to **Enable**.
- Click on Enable and OK
- 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.
- Click on **Enable** and **OK**
- 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" next to the file name. To exit VS Code, **File->Exit**.
Debugging with VS Code
----
- Open a file folder (**File->Open Folder**) where contains the PowerShell modules or scripts you have written already and want to debug. In this example, we saved helloworld.ps1 under home/jen/debug. Thus we select the "debug" folder and open it in VS Code.
- Open a file folder (**File->Open Folder**) that contains the PowerShell modules or scripts you have written already and want to debug. In this example, we saved the helloworld.ps1 under a directory called "demo". Thus we select the "demo" folder and open it in VS Code.
- Creating the Debug Configuration (launch.json)
Because some information regarding your scripts is needed for debugger to start executing your script, we need to set up the debug config First. This is one time only to debug PowerShell scripts under your current folder.
Because some information regarding your scripts is needed for debugger to start executing your script, we need to set up the debug config first. This is one-time process to debug PowerShell scripts under your current folder. In our case, the "demo" folder.
* Click on the **Debug** icon (or **Ctrl+Shift+D**)
* Click on the **Settings** icon that looks like a gear. The VS Code will prompt you to **Select Environment**. Choose **PowerShell**. Then the VS code will auto create a debug configuration settings file in the same folder. It looks like the following:
* Click on the **Settings** icon that looks like a gear. VS Code will prompt you to **Select Environment**. Choose **PowerShell**. Then VS code will auto create a debug configuration settings file in the same folder. It looks like the following:
```json
{
"version": "0.2.0",
@@ -73,9 +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** on a line you wish to debug break into.
- Once the debug configuration is established, go to your helloworld.ps1 and set a breakpoint by pressing **F9** on a line you wish to debug.
- To disable the breakpoint, press **F9** again.
- Press **F5** to let the run.
- Press **F5** to run the script. The execution should stop on the line you put the breakpoint on.
- Press **F5** to continue running the script.
There are a few blogs that may be helpful to get you started using PowerShell extension for VS Code