mirrors/PowerShell
0
0
Fork 0
mirror of https://github.com/PowerShell/PowerShell.git synced 2024-11-26 19:34:22 +08:00
Code Issues Packages Projects Releases Wiki Activity

Migrate user docs to the PowerShell-Docs repo (#19871)

Browse Source
This commit is contained in:
Sean Wheeler 2023-07-10 16:10:38 -05:00 committed by GitHub
parent 5ec04f1f4e
commit d9fff5bea9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 99 additions and 885 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
.spelling
View File

@ -1338,6 +1338,13 @@ microsoft.extensions.objectpool
microsoft.codeanalysis.analyzers
benchmarkdotnet
winforms
MicrosoftDocs
about_Scripts
debugging-from-commandline
about_Object_Creation
about_Functions_Advanced
Microsoft.PowerShell.SDK
NuGet.org.
- CHANGELOG.md
aavdberg
asrosent
@ -1740,3 +1747,9 @@ preview.3.23178.7
PoolNames
techguy16
sdwheeler
MicrosoftDocs
about_Scripts
about_Object_Creation
about_Functions_Advanced
Microsoft.PowerShell.SDK
NuGet.org.

46
docs/DOCSMIGRATION.md
View File

@ -1,20 +1,38 @@
# Documentation Migration
The docs folder in this repo contains a lot of documentation about the PowerShell source code and build environment.
It also has contained documentation about installing and using PowerShell.
That documentation belongs in the [PowerShell/PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repo.
The docs folder in this repository contains documentation about the PowerShell source code and build
environment.
We are in the process of migrating the user-focused articles to the docs repo.
This file records which files have been migrated.
User-focused documentation has been moved to the [MicrosoftDocs/PowerShell-Docs][01] repository.
## 2018-05-18
The files from the `learning-powershell` folder have been removed from this repository. This list
provides links to suitable replacements.
The following files have been moved to the PowerShell/PowerShell-Docs repo.
- **create-powershell-scripts.md**
- [about_Scripts][06]
- **debugging-from-commandline.md**
- [about_Debuggers][04]
- **powershell-beginners-guide.md**
- [PowerShell 101][09]
- **README.md**
- [Install PowerShell on Windows, Linux, and macOS][07]
- [Using Visual Studio Code (VS Code)][11]
- [Pester Guides][02]
- [Writing Pester Tests Guidelines][03]
- [PowerShell learning resources][08]
- **working-with-powershell-objects.md**
- [about_Object_Creation][05]
- [Crescendo overview][10]
| Original file location | New location in PowerShell/PowerShell-Docs |
|--------------------------------|----------------------------------------------------------------------------|
| `docs/installation/linux.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Linux.md` |
| `docs/installation/macos.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS.md` |
| `docs/installation/windows.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md` |
| `docs/BREAKINGCHANGES.md` | `reference/docs-conceptual/whats-new/breaking-changes-ps6.md` |
| `docs/KNOWNISSUES.md` | `reference/docs-conceptual/whats-new/known-issues-ps6.md` |
<!-- link references -->
[01]: https://github.com/MicrosoftDocs/PowerShell-Docs
[02]: https://github.com/pester/Pester
[03]: https://github.com/PowerShell/PowerShell/blob/master/docs/testing-guidelines/WritingPesterTests.md
[04]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_debuggers
[05]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_object_creation
[06]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scripts
[07]: https://learn.microsoft.com/powershell/scripting/install/installing-powershell
[08]: https://learn.microsoft.com/powershell/scripting/learn/more-powershell-learning
[09]: https://learn.microsoft.com/powershell/scripting/learn/ps101/00-introduction
[10]: https://learn.microsoft.com/powershell/utility-modules/crescendo/overview?view=ps-modules
[11]: https://learn.microsoft.com/powershell/scripting/dev-cross-plat/vscode/using-vscode

96
docs/FAQ.md
View File

@ -2,89 +2,86 @@
## Where can I learn PowerShell's syntax?
[SS64.com](https://ss64.com/ps/syntax.html) is a good resource.
[Microsoft Docs](https://docs.microsoft.com/powershell/scripting/overview) is another excellent resource.
- [What is PowerShell?][12]
- [Discover PowerShell][09]
- [PowerShell 101][11]
- [PowerShell learning resources][10]
## What are the best practices and style?
The [PoshCode][] unofficial guide is our reference.
[PoshCode]: https://github.com/PoshCode/PowerShellPracticeAndStyle
The [PoshCode][03] unofficial guide is our reference.
## What are PowerShell's scoping rules?
- Variables are created in your current scope unless explicitly indicated.
- Variables are visible in a child scope unless explicitly indicated.
- Variables created in a child scope are not visible to a parent unless
explicitly indicated.
- Variables created in a child scope are not visible to a parent unless explicitly indicated.
- Variables may be placed explicitly in a scope.
### Things that create a scope
- [functions](https://ss64.com/ps/syntax-functions.html)
- [call operator](https://ss64.com/ps/call.html) (`& { }`)
- [script invocations](https://ss64.com/ps/syntax-run.html)
- [about_Functions_Advanced][04]
- [about Operators - Call operator][06] (`& { }`)
- [about Scopes][08]
### Things that operate in the current scope
- [source operator](https://ss64.com/ps/source.html) (`. { }`)
- [statements](https://ss64.com/ps/statements.html) (`if .. else`, `for`, `switch`, etc.)
- [about Operators - Dot source operator][07] (`. { }`)
- [about Language Keywords][05] (`if .. else`, `for`, `switch`, etc.)
## Why didn't an error throw an exception?
Error handling in PowerShell is a bit weird, as not all errors result in catchable exceptions by default.
Setting `$ErrorActionPreference = 'Stop'` will likely do what you want;
that is, cause non-terminating errors instead to terminate.
Read [An Introduction To Error Handling in PowerShell][error] for more information.
[error]: https://gist.github.com/TravisEz13/9bb811c63b88501f3beec803040a9996
Error handling in PowerShell is unique, as not all errors result in catchable exceptions by default.
Setting `$ErrorActionPreference = 'Stop'` will likely do what you want; that is, cause
non-terminating errors instead to terminate. Read the [GitHub issue][02] for more information.
## Where do I get the PowerShell Core SDK package?
The SDK NuGet package `Microsoft.PowerShell.SDK` is provided for developers to write .NET Core C# code targeting PowerShell Core.
PowerShell NuGet packages for releases starting from v6.0.0-alpha.9 will be published to the [powershell-core][] myget feed.
The SDK NuGet package **Microsoft.PowerShell.SDK** is provided for developers to write C# code
targeting PowerShell. PowerShell NuGet packages are published to [Microsoft.PowerShell.SDK][13] on
NuGet.org.
To use the `Microsoft.PowerShell.SDK` NuGet package, declare `PackageReference` tags in your `.csproj` file as follows:
To use the `Microsoft.PowerShell.SDK` NuGet package, declare `PackageReference` tags in your
`.csproj` file as follows:
```xml
<ItemGroup>
<PackageReference Include="Microsoft.PowerShell.SDK" Version="6.0.0-beta.9" />
<PackageReference Include="Microsoft.PowerShell.Commands.Diagnostics" Version="6.0.0-beta.9" />
<PackageReference Include="Microsoft.WSMan.Management" Version="6.0.0-beta.9"/>
<PackageReference Include="Microsoft.PowerShell.SDK" Version="7.3.5" />
<PackageReference Include="Microsoft.PowerShell.Commands.Diagnostics" Version="7.3.5" />
<PackageReference Include="Microsoft.WSMan.Management" Version="7.3.5"/>
</ItemGroup>
```
[powershell-core]: https://powershell.myget.org/gallery/powershell-core
## Why did my build fail?
There are few common issues with the build.
The easiest way to resolve most issues with the build is to run `Start-PSBuild -Clean`.
There are few common issues with the build. The easiest way to resolve most issues with the build is
to run `Start-PSBuild -Clean`.
### Dependency changed
If package dependencies were changed in any `project.json`, you need to manually
run `dotnet restore` to update your local dependency graphs.
`Start-PSBuild -Restore` can automatically do this.
If package dependencies were changed in any `project.json`, you need to manually run
`dotnet restore` to update your local dependency graphs. `Start-PSBuild -Restore` can automatically
do this.
### Resource changed
`Start-PSBuild` automatically calls `Start-ResGen` on the very first run.
On subsequent runs, you may need to explicitly use `Start-PSBuild -ResGen` command.
`Start-PSBuild` automatically calls `Start-ResGen` on the very first run. On subsequent runs, you
may need to explicitly use `Start-PSBuild -ResGen` command.
Try it, when you see compilation error about *strings.
[More details](dev-process/resx-files.md) about resource.
[More details][01] about resource.
### TypeGen
Similar to `-ResGen` parameter, there is `-TypeGen` parameter that triggers regeneration of type catalog.
Similar to `-ResGen` parameter, there is `-TypeGen` parameter that triggers regeneration of type
catalog.
## Why did `Start-PSBuild` tell me to update `dotnet`?
We depend on the latest version of the .NET CLI, as we use the output of `dotnet
--info` to determine the current runtime identifier.
Without this information, our build function can't know where `dotnet` is going to place the build artifacts.
We depend on the latest version of the .NET CLI, as we use the output of `dotnet --info` to
determine the current runtime identifier. Without this information, our build function can't know
where `dotnet` is going to place the build artifacts.
You can automatically install this using `Start-PSBootstrap`.
**However, you must first manually uninstall other versions of the CLI.**
@ -98,7 +95,22 @@ If you have installed by using any of the following means:
You *must* manually uninstall it.
Additionally, if you've just unzipped their binary drops (or used their obtain
scripts, which do essentially the same thing), you must manually delete the
folder, as the .NET CLI team re-engineered how their binaries are setup, such
that new packages' binaries get stomped on by old packages' binaries.
Additionally, if you've just unzipped their binary drops (or used their obtain scripts, which do
essentially the same thing), you must manually delete the folder, as the .NET CLI team re-engineered
how their binaries are setup, such that new packages' binaries get stomped on by old packages'
binaries.
<!-- updated link references -->
[01]: dev-process/resx-files.md
[02]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/1583
[03]: https://github.com/PoshCode/PowerShellPracticeAndStyle
[04]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced
[05]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_language_keywords
[06]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators#call-operator-
[07]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators#dot-sourcing-operator-
[08]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scopes
[09]: https://learn.microsoft.com/powershell/scripting/discover-powershell
[10]: https://learn.microsoft.com/powershell/scripting/learn/more-powershell-learning
[11]: https://learn.microsoft.com/powershell/scripting/learn/ps101/00-introduction
[12]: https://learn.microsoft.com/powershell/scripting/overview
[13]: https://www.nuget.org/packages/Microsoft.PowerShell.SDK

127
docs/learning-powershell/README.md
View File

@ -1,127 +0,0 @@
# Learning PowerShell
Whether you're a Developer, a DevOps or an IT Professional, this doc will help you getting started with PowerShell.
In this document we'll cover the following:
Installing PowerShell, samples walkthrough, PowerShell editor, debugger, testing tools and a map book for experienced bash users to get started with PowerShell faster.
The exercises in this document are intended to give you a solid foundation in how to use PowerShell.
You won't be a PowerShell guru at the end of reading this material but you will be well on your way with the right set of knowledge to start using PowerShell.
If you have 30 minutes now, let’s try it.
## Installing PowerShell
First you need to set up your computer working environment if you have not done so.
Choose the platform below and follow the instructions.
At the end of this exercise, you should be able to launch the PowerShell session.
- Get PowerShell by installing package
* [PowerShell on Linux][inst-linux]
* [PowerShell on macOS][inst-macos]
* [PowerShell on Windows][inst-win]
For this tutorial, you do not need to install PowerShell if you are running on Windows.
You can launch PowerShell console by pressing Windows key, typing PowerShell, and clicking on Windows PowerShell.
However if you want to try out the latest PowerShell, follow the [PowerShell on Windows][inst-win].
- Alternatively you can get the PowerShell by [building it][build-powershell]
[build-powershell]:../../README.md#building-the-repository
[inst-linux]: https://docs.microsoft.com/powershell/scripting/install/installing-powershell-core-on-linux
[inst-win]: https://docs.microsoft.com/powershell/scripting/install/installing-powershell-core-on-windows
[inst-macos]: https://docs.microsoft.com/powershell/scripting/install/installing-powershell-core-on-macos
## Getting Started with PowerShell
PowerShell commands follow a Verb-Noun semantic 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 from the [PowerShell Beginner's Guide](powershell-beginners-guide.md).
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 a text editor.
You can use your favorite editor to write scripts.
We use Visual Studio Code (VS Code) which works on Windows, Linux, and macOS.
Click on the following link to create your first PowerShell script.
- [Using Visual Studio Code (VS Code)](https://docs.microsoft.com/powershell/scripting/dev-cross-plat/vscode/using-vscode)
### PowerShell Debugger
Debugging can help you find bugs and fix problems in your PowerShell scripts.
Click on the link below to learn more about debugging:
- [Using Visual Studio Code (VS Code)](https://docs.microsoft.com/powershell/scripting/dev-cross-plat/vscode/using-vscode#debugging-with-visual-studio-code)
- [PowerShell Command-line Debugging][cli-debugging]
[cli-debugging]:./debugging-from-commandline.md
### PowerShell Testing
We recommend using Pester testing tool which is initiated by the PowerShell Community for writing test cases.
To use the tool please read [Pester Guides](https://github.com/pester/Pester) and [Writing Pester Tests Guidelines](https://github.com/PowerShell/PowerShell/blob/master/docs/testing-guidelines/WritingPesterTests.md).
### Map Book for Experienced Bash users
The table below lists the usage of some basic commands to help you get started on PowerShell faster.
Note that all bash commands should continue working on PowerShell session.
| Bash | PowerShell | Description
|:--------------------------------|:----------------------------------------|:---------------------
| ls | dir, Get-ChildItem | List files and folders
| tree | dir -Recurse, Get-ChildItem -Recurse | List all files and folders
| cd | cd, Set-Location | Change directory
| pwd | pwd, $pwd, Get-Location | Show working directory
| clear, Ctrl+L, reset | cls, clear | Clear screen
| mkdir | New-Item -ItemType Directory | Create a new folder
| touch test.txt | New-Item -Path test.txt | Create a new empty file
| cat test1.txt test2.txt | Get-Content test1.txt, test2.txt | Display files contents
| cp ./source.txt ./dest/dest.txt | Copy-Item source.txt dest/dest.txt | Copy a file
| cp -r ./source ./dest | Copy-Item ./source ./dest -Recurse | Recursively copy from one folder to another
| mv ./source.txt ./dest/dest.txt | Move-Item ./source.txt ./dest/dest.txt | Move a file to other folder
| rm test.txt | Remove-Item test.txt | Delete a file
| rm -r &lt;folderName> | Remove-Item &lt;folderName> -Recurse | Delete a folder
| find -name build* | Get-ChildItem build* -Recurse | Find a file or folder starting with 'build'
| grep -Rin "sometext" --include="*.cs" |Get-ChildItem -Recurse -Filter *.cs <br> \| Select-String -Pattern "sometext" | Recursively case-insensitive search for text in files
| curl https://github.com | Invoke-RestMethod https://github.com | Transfer data to or from the web
### Recommended Training and Reading
- Microsoft Virtual Academy: [Getting Started with PowerShell][getstarted-with-powershell]
- [Why Learn PowerShell][why-learn-powershell] by Ed Wilson
- PowerShell Web Docs: [Basic cookbooks][basic-cookbooks]
- [The Guide to Learning PowerShell][ebook-from-Idera] by Tobias Weltner
- [PowerShell-related Videos][channel9-learn-powershell] on Channel 9
- [PowerShell Quick Reference Guides][quick-reference] by PowerShellMagazine.com
- [PowerShell Tips][idera-powershell-tips] from Idera
- [PowerShell 5 How-To Videos][script-guy-how-to] by Ed Wilson
- [PowerShell Documentation](https://docs.microsoft.com/powershell)
- [Interactive learning with PSKoans](https://aka.ms/pskoans)
### Commercial Resources
- [Windows PowerShell in Action][in-action] by [Bruce Payette](https://github.com/brucepay)
- [Introduction to PowerShell][powershell-intro] from Pluralsight
- [PowerShell Training and Tutorials][lynda-training] from Lynda.com
- [Learn Windows PowerShell in a Month of Lunches][learn-win-powershell] by Don Jones and Jeffrey Hicks
- [Learn PowerShell in a Month of Lunches][learn-powershell] by Travis Plunk (@TravisEz13),
Tyler Leonhardt (@tylerleonhardt), Don Jones, and Jeffery Hicks
[in-action]: https://www.amazon.com/Windows-PowerShell-Action-Second-Payette/dp/1935182137
[powershell-intro]: https://www.pluralsight.com/courses/powershell-intro
[lynda-training]: https://www.lynda.com/PowerShell-training-tutorials/5779-0.html
[learn-win-powershell]: https://www.amazon.com/Learn-Windows-PowerShell-Month-Lunches/dp/1617294160
[learn-powershell]: https://www.manning.com/books/learn-powershell-in-a-month-of-lunches
[getstarted-with-powershell]: https://channel9.msdn.com/Series/GetStartedPowerShell3
[why-learn-powershell]: https://blogs.technet.microsoft.com/heyscriptingguy/2014/10/18/weekend-scripter-why-learn-powershell/
[ebook-from-Idera]:https://www.idera.com/resourcecentral/whitepapers/powershell-ebook
[channel9-learn-powershell]: https://channel9.msdn.com/Search?term=powershell#ch9Search
[idera-powershell-tips]: https://blog.idera.com/database-tools/powershell/powertips/
[quick-reference]: https://www.powershellmagazine.com/2014/04/24/windows-powershell-4-0-and-other-quick-reference-guides/
[script-guy-how-to]:https://blogs.technet.microsoft.com/tommypatterson/2015/09/04/ed-wilsons-powershell5-videos-now-on-channel9-2/
[basic-cookbooks]:https://docs.microsoft.com/powershell/scripting/samples/sample-scripts-for-administration

65
docs/learning-powershell/create-powershell-scripts.md
View File

@ -1,65 +0,0 @@
# How to Create and Run PowerShell Scripts
You can combine a series of commands in a text file and save it with the file extension '.ps1', and the file will become a PowerShell script.
This would begin by opening your favorite text editor and pasting in the following example.
```powershell
# Script to return current IPv4 addresses on a Linux or MacOS host
$ipInfo = ifconfig | Select-String 'inet'
$ipInfo = [regex]::matches($ipInfo,"addr:\b(?:\d{1,3}\.){3}\d{1,3}\b") | ForEach-Object value
foreach ($ip in $ipInfo)
{
$ip.Replace('addr:','')
}
```
Then save the file to something memorable, such as .\NetIP.ps1.
In the future when you need to get the IP addresses for the node, you can simplify this task by executing the script.
```powershell
.\NetIP.ps1
10.0.0.1
127.0.0.1
```
You can accomplish this same task on Windows.
```powershell
# One line script to return current IPv4 addresses on a Windows host
Get-NetIPAddress | Where-Object {$_.AddressFamily -eq 'IPv4'} | ForEach-Object IPAddress
```
As before, save the file as .\NetIP.ps1 and execute within a PowerShell environment.
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.
```powershell
NetIP.ps1
127.0.0.1
10.0.0.1
```
## Creating a script that can accomplish the same task on multiple operating systems
If you would like to author one script that will return the IP address across Linux, MacOS, or Windows, you could accomplish this using an IF statement.
```powershell
# Script to return current IPv4 addresses for Linux, MacOS, or Windows
$IP = if ($IsLinux -or $IsMacOS)
{
$ipInfo = ifconfig | Select-String 'inet'
$ipInfo = [regex]::matches($ipInfo,"addr:\b(?:\d{1,3}\.){3}\d{1,3}\b") | ForEach-Object value
foreach ($ip in $ipInfo) {
$ip.Replace('addr:','')
}
}
else
{
Get-NetIPAddress | Where-Object {$_.AddressFamily -eq 'IPv4'} | ForEach-Object IPAddress
}
# Remove loopback address from output regardless of platform
$IP | Where-Object {$_ -ne '127.0.0.1'}
```
[run-ps]:https://www.itprotoday.com/powershell/running-powershell-scripts-easy-1-2-3

173
docs/learning-powershell/debugging-from-commandline.md
View File

@ -1,173 +0,0 @@
# Debugging in PowerShell Command-line
As we know, we can debug PowerShell code via GUI tools like [Visual Studio Code](https://docs.microsoft.com/powershell/scripting/dev-cross-plat/vscode/using-vscode#debugging-with-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.
```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"
```
## 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>
```
## 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
./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://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_debuggers)
- [PowerShell Debugging](https://blogs.technet.microsoft.com/heyscriptingguy/tag/debugging/)

339
docs/learning-powershell/powershell-beginners-guide.md
View File

@ -1,339 +0,0 @@
# PowerShell Beginner’s Guide
If you are new to PowerShell, this document will walk you through a few examples to give you some basic ideas of PowerShell.
We recommend that you open a PowerShell console/session and type along with the instructions in this document to get most out of this exercise.
## Launch PowerShell Console/Session
First you need to launch a PowerShell session by following the [Installing PowerShell Guide](./README.md#installing-powershell).
## Getting Familiar with PowerShell Commands
In this section, you will learn how to
- create a file, delete a file and change file directory
- discover what version of PowerShell you are currently using
- exit a PowerShell session
- get help if you needed
- find syntax of PowerShell cmdlets
- and more
As mentioned above, PowerShell commands are 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 />** as it appears on Linux in the following examples.
It is shown as `PS C:\>` on Windows.
1. `Get-Process`: Gets the processes that are running on the local computer or a remote computer.
By default, you will get data back similar to the following:
```powershell
PS /> Get-Process
Handles NPM(K) PM(K) WS(K) CPU(s) Id ProcessName
------- ------ ----- ----- ------ -- -----------
- - - 1 0.012 12 bash
- - - 21 20.220 449 powershell
- - - 11 61.630 8620 code
- - - 74 403.150 1209 firefox
…
```
Only interested in the instance of Firefox process that is running on your computer?
Try this:
```powershell
PS /> Get-Process -Name firefox
Handles NPM(K) PM(K) WS(K) CPU(s) Id ProcessName
------- ------ ----- ----- ------ -- -----------
- - - 74 403.150 1209 firefox
```
Want to get back more than one process?
Then just specify process names and separate them with commas.
```powershell
PS /> Get-Process -Name firefox, powershell
Handles NPM(K) PM(K) WS(K) CPU(s) Id ProcessName
------- ------ ----- ----- ------ -- -----------
- - - 74 403.150 1209 firefox
- - - 21 20.220 449 powershell
```
1. `Clear-Host`: Clears the display in the host program.
```powershell
PS /> Get-Process
PS /> Clear-Host
```
Type too much just for clearing the screen?
Here is how the alias can help.
1. `Get-Alias`: Gets the aliases for the current session.
```powershell
Get-Alias
CommandType Name
----------- ----
…
Alias cd -> Set-Location
Alias cls -> Clear-Host
Alias clear -> Clear-Host
Alias copy -> Copy-Item
Alias dir -> Get-ChildItem
Alias gc -> Get-Content
Alias gmo -> Get-Module
Alias ri -> Remove-Item
Alias type -> Get-Content
…
```
As you can see `cls` or `clear` is an alias of `Clear-Host`.
Now try it:
```powershell
PS /> Get-Process
PS /> cls
```
1. `cd -> Set-Location`: Sets the current working location to a specified location.
```powershell
PS /> Set-Location /home
PS /home>
```
1. `dir -> Get-ChildItem`: Gets the items and child items in one or more specified locations.
```powershell
# Get all files under the current directory:
PS /> Get-ChildItem
# Get all files under the current directory as well as its subdirectories:
PS /> cd $home
PS /home/jen> dir -Recurse
# List all files with "txt" file extension.
PS /> cd $home
PS /home/jen> dir –Path *.txt -Recurse
```
1. `New-Item`: Creates a new item.
```powershell
# An empty file is created if you type the following:
PS /home/jen> New-Item -Path ./test.txt
Directory: /home/jen
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 7/7/2016 7:17 PM 0 test.txt
```
You can use the `-Value` parameter to add some data to your file.
For example, the following command adds the phrase `Hello world!` as a file content to the `test.txt`.
Because the test.txt file exists already, we use `-Force` parameter to replace the existing content.
```powershell
PS /home/jen> New-Item -Path ./test.txt -Value "Hello world!" -Force
Directory: /home/jen
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 7/7/2016 7:19 PM 24 test.txt
```
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.txt -Value "Hello world again!"
```
Or simply use `>` as below:
```powershell
# create an empty file
"" > test.txt
# set "Hello world!" as content of test.txt file
"Hello world!!!" > test.txt
```
The pound sign `#` above is used for comments in PowerShell.
1. `type -> Get-Content`: Gets the content of the item at the specified location.
```powershell
PS /home/jen> Get-Content -Path ./test.txt
PS /home/jen> type -Path ./test.txt
Hello world again!
```
1. `del -> Remove-Item`: Deletes the specified items.
This cmdlet will delete the file `/home/jen/test.txt`:
```powershell
PS /home/jen> Remove-Item ./test.txt
```
1. `$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 6.0.0-alpha
PSEdition Core
PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...}
BuildVersion 3.0.0.0
GitCommitId v6.0.0-alpha.12
CLRVersion
WSManStackVersion 3.0
PSRemotingProtocolVersion 2.3
SerializationVersion 1.1.0.1
```
1. `Exit`: To exit the PowerShell session, type `exit`.
```powershell
exit
```
## Need Help?
The most important command in PowerShell is possibly the `Get-Help`, which allows you to quickly learn PowerShell without having to search around the internet.
The `Get-Help` cmdlet also shows you how PowerShell commands work with examples.
It shows the syntax and other technical information of the `Get-Process` cmdlet.
```powershell
PS /> Get-Help -Name Get-Process
```
It displays the examples how to use the `Get-Process` cmdlet.
```powershell
PS />Get-Help -Name Get-Process -Examples
```
If you use **-Full** parameter, for example, `Get-Help -Name Get-Process -Full`, it will display more technical information.
## Discover Commands Available on Your System
You want to discover what PowerShell cmdlets available on your system? Just run `Get-Command` as below:
```powershell
PS /> Get-Command
```
If you want to know whether a particular cmdlet exists on your system, you can do something like below:
```powershell
PS /> Get-Command Get-Process
```
If you want to know the syntax of `Get-Process` cmdlet, type:
```powershell
PS /> Get-Command Get-Process -Syntax
```
If you want to know how to use the `Get-Process`, type:
```powershell
PS /> Get-Help Get-Process -Example
```
## PowerShell Pipeline `|`
Sometimes when you run Get-ChildItem or "dir", you want to get a list of files and folders in a descending order.
To achieve that, type:
```powershell
PS /home/jen> dir | Sort-Object -Descending
```
Say you want to get the largest file in a directory
```powershell
PS /home/jen> dir | Sort-Object -Property Length -Descending | Select-Object -First 1
Directory: /home/jen
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 5/16/2016 1:15 PM 32972 test.log
```
## How to Create and Run PowerShell scripts
You can use Visual Studio Code or your favorite editor to create a PowerShell script and save it with a `.ps1` file extension.
For more details, see [Create and Run PowerShell Script Guide][create-run-script]
## Recommended Training and Reading
- Video: [Get Started with PowerShell][remoting] from Channel9
- [eBooks from PowerShell.org](https://leanpub.com/u/devopscollective)
- [eBooks List][ebook-list] by Martin Schvartzman
- [Tutorial from MVP][tutorial]
- Script Guy blog: [The best way to Learn PowerShell][to-learn]
- [Understanding PowerShell Module][ps-module]
- [How and When to Create PowerShell Module][create-ps-module] by Adam Bertram
- Video: [PowerShell Remoting in Depth][in-depth] from Channel9
- [PowerShell Basics: Remote Management][remote-mgmt] from ITPro
- [Running Remote Commands][remote-commands] from PowerShell Web Docs
- [Samples for Writing a PowerShell Script Module][examples-ps-module]
- [Writing a PowerShell module in C#][writing-ps-module]
- [Examples of Cmdlets Code][sample-code]
## Commercial Resources
- [Windows PowerShell in Action][in-action] by Bruce Payette
- [Windows PowerShell Cookbook][cookbook] by Lee Holmes
[in-action]: https://www.amazon.com/Windows-PowerShell-Action-Bruce-Payette/dp/1633430294
[cookbook]: http://shop.oreilly.com/product/9780596801519.do
[ebook-list]: https://martin77s.wordpress.com/2014/05/26/free-powershell-ebooks/
[tutorial]: https://www.computerperformance.co.uk/powershell/index-13/
[to-learn]:https://blogs.technet.microsoft.com/heyscriptingguy/2015/01/04/weekend-scripter-the-best-ways-to-learn-powershell/
[ps-module]:https://docs.microsoft.com/powershell/scripting/developer/module/understanding-a-windows-powershell-module
[create-ps-module]:https://www.business.com/articles/powershell-modules/
[remoting]:https://channel9.msdn.com/Series/GetStartedPowerShell3/06
[in-depth]: https://docs.microsoft.com/en-us/events/mms-2012/sv-b406
[remote-mgmt]:https://www.itprotoday.com/powershell/powershell-basics-remote-management
[remote-commands]:https://docs.microsoft.com/powershell/scripting/learn/remoting/running-remote-commands
[examples-ps-module]:https://docs.microsoft.com/powershell/scripting/developer/module/how-to-write-a-powershell-script-module
[writing-ps-module]:https://www.powershellmagazine.com/2014/03/18/writing-a-powershell-module-in-c-part-1-the-basics/
[sample-code]:https://docs.microsoft.com/powershell/scripting/developer/cmdlet/examples-of-cmdlet-code
[create-run-script]:./create-powershell-scripts.md

125
docs/learning-powershell/working-with-powershell-objects.md
View File

@ -1,125 +0,0 @@
# Working with PowerShell Objects
When cmdlets are executed in PowerShell, the output is an Object, as opposed to only returning text.
This provides the ability to store information as properties.
As a result, handling large amounts of data and getting only specific properties is a trivial task.
As a simple example, the following function retrieves information about storage Devices on a Linux or MacOS operating system platform.
This is accomplished by parsing the output of an existing command, *parted -l* in administrative context, and creating an object from the raw text by using the *New-Object* cmdlet.
```powershell
function Get-DiskInfo
{
$disks = sudo parted -l | Select-String "Disk /dev/sd*" -Context 1,0
$diskinfo = @()
foreach ($disk in $disks) {
$diskline1 = $disk.ToString().Split("`n")[0].ToString().Replace(' Model: ','')
$diskline2 = $disk.ToString().Split("`n")[1].ToString().Replace('> Disk ','')
$i = New-Object psobject -Property @{'Friendly Name' = $diskline1; Device=$diskline2.Split(': ')[0]; 'Total Size'=$diskline2.Split(':')[1]}
$diskinfo += $i
}
$diskinfo
}
```
Execute the function and store the results as a variable.
Now retrieve the value of the variable.
The results are formatted as a table with the default view.
*Note: in this example, the disks are virtual disks in a Microsoft Azure virtual machine.*
```powershell
PS /home/psuser> $d = Get-DiskInfo
[sudo] password for psuser:
PS /home/psuser> $d
Friendly Name Total Size Device
------------- ---------- ------
Msft Virtual Disk (scsi) 31.5GB /dev/sda
Msft Virtual Disk (scsi) 145GB /dev/sdb
```
Passing the variable down the pipeline to *Get-Member* reveals available methods and properties.
This is because the value of *$d* is not just text output.
The value is actually an array of .Net objects with methods and properties.
The properties include Device, Friendly Name, and Total Size.
```powershell
PS /home/psuser> $d | Get-Member
TypeName: System.Management.Automation.PSCustomObject
Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
Device NoteProperty string Device=/dev/sda
Friendly Name NoteProperty string Friendly Name=Msft Virtual Disk (scsi)
Total Size NoteProperty string Total Size= 31.5GB
```
To confirm, we can call the GetType() method interactively from the console.
```powershell
PS /home/psuser> $d.GetType()
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True Object[] System.Array
```
To index in to the array and return only specific objects, use the square brackets.
```powershell
PS /home/psuser> $d[0]
Friendly Name Total Size Device
------------- ---------- ------
Msft Virtual Disk (scsi) 31.5GB /dev/sda
PS /home/psuser> $d[0].GetType()
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True False PSCustomObject System.Object
```
To return a specific property, the property name can be called interactively from the console.
```powershell
PS /home/psuser> $d.Device
/dev/sda
/dev/sdb
```
To output a view of the information other than default, such as a view with only specific properties selected, pass the value to the *Select-Object* cmdlet.
```powershell
PS /home/psuser> $d | Select-Object Device, 'Total Size'
Device Total Size
------ ----------
/dev/sda 31.5GB
/dev/sdb 145GB
```
Finally, the example below demonstrates use of the *ForEach-Object* cmdlet to iterate through the array and manipulate the value of a specific property of each object.
In this case the Total Size property, which was given in Gigabytes, is changed to Megabytes.
Alternatively, index in to a position in the array as shown below in the third example.
```powershell
PS /home/psuser> $d | ForEach-Object 'Total Size'
31.5GB
145GB
PS /home/psuser> $d | ForEach-Object {$_.'Total Size' / 1MB}
32256
148480
PS /home/psuser> $d[1].'Total Size' / 1MB
148480
```