PowerShell

PowerShell for Beginners (Part 4): The PowerShell Help (Get-Help)

Now, after the third part PowerShell for Beginners (Part 3): The Parameters, we’ll concentrate on the PowerShell help. But before we begin the answer of the third exercise. We will also do a quick review what we’ve learned so far.

All parts of the series can be found here: PowerShell for Beginners (Series)

Review (Part 3)

Exercise

In the third part I asked why this command is not working:

Why does this command not work?

Unbenannt.JPG

The first task is to find out the parameters for the filter *.txt and for the path C:\Temp.


Get-Help Get-ChildItem -Parameter *

Once we’ve found the path and filter parameter we can see that they are positional.

1.JPG

2.JPG

This means that Path does not require the parameter name (otherwise the position value must be named), but it’s parameter value must be the first or only unnamed parameter value in the command. This also means that the first argument of the call will be automatically bound to the path parameter. But our first argument defines the filter (*.txt), not the path. This one works, because the value of the path is at the first position and the value of the filter is on the second position:


Get-ChildItem C:\Temp\ *.txt

 

Summary


Parameters are different. There are required, positional, switched, mandatory and not mandatory parameters. Get-Help can help you exploring all parameters of a command. To do this run Get-Help Your-Command -Parameter *. Use TAB whenever possible.


 

A few words about the PowerShell Help at the beginning

We’ve already learned how to use the help to explore parameters. Now we make a huge step forward. This part is all about the help and using the help. The PowerShell help is a wonderful source to learn and discover new things. I’m  truly convinced that if you are not familiar with the help you will never become a good PowerShell guy.

Don Jones, the author of “Learn PowerShell in a month of lunches” and PowerShell MVP veteran said:

“Be prepared to read the help, or you’ll fail at PowerShell.”

You can call up the help with the cmdlet Get-Help. This informs you that the detailed version of the help is only available online. But the good news is: You are able to download it.

Unbenannt.PNG

Online Help

We will download the help files later. There’s a workaround. To use the full help for the command Get-ChildItem run


Get-Help Get-ChildItem -Online

Once executed a browser window appears that redirects you to the Microsoft PowerShell Online Help.

1.JPG

It’s worth to take a look at the examples below. They are great.

Unbenannt.JPG

Unbenannt.JPG

The examples and the detailed help are not stored by default on computers running Windows. We are now going to download the help files from an online repository.

Review


PowerShell is shipped with a slimmed Help. There’s an extensive Online Help. The examples are the heart of the help. Get-Help Your-Command -Online opens the online help in a web browser.


Downloading the Full Help

Use Update-Help to download the help. This is an example how to download the help files for the culture en-US (English).  Open Windows PowerShell. Run


Update-Help -UICulture 'en-US' -Force

Unbenannt.JPG

Please note that you can run the command without -Force only once a day per IP-Address. So, if you are behind a NAT device configured to translate addresses in an overload mode (PAT), then be aware that you have to provide the Force parameter, because all clients go to the internet with the same public IP-Address and the download for this public IP-Address is allowed once per day.

Now the full scope of the help is installed. It’s time to play with it.

Using the Help

Get-Help offers a wide range of parameters. Type Get-Help and then type and hold CTRL + SPACE to see all of them.

Unbenannt.PNG

To get the help content of Get-ChildItem type


Get-Help Get-ChildItem

or


Help Get-ChildItem

Note: Help is the alias for Get-Help.

unbenannt22.jpg

This shows the small version of the Help. For beginners it can be frustrating reading the help this way. It offers no examples and no detailed information about the use of the command. Let´s move on with the Example Parameter, which is more useful for “learning by doing”.

What have we learned so far?


The full help is downloaded using the command Update-Help. Help is the alias for Get-Help. Running Get-Help without any parameter shows you the small version of the help. 


A useful parameter: ShowWindow

If you prefer a pop-up window, use the parameter ShowWindow.


Get-Help Get-ChildItem -ShowWindow

Unbenannt.PNG

The Examples

The PowerShell help examples are a really great and excellently suitable source for doing your first steps with PowerShell. For getting the Get-ChildItem examples type


Get-Help Get-ChildItem -Examples

Unbenannt.PNG

Unbenannt.PNG

Another example shows how to use Powershell Attributes with Get-Date. We haven’t learned that yet. But that’s not a broken leg, we can get a taste of it.


Help Get-Date -Examples

Scroll down look for Example 4.

Unbenannt.JPG

Now you can start playing. For example, you can modify the command and fill in your date of birth.

Tip: Type (Get-Date). then Press CTRL + SPACE. Have fun while exploring the attributes of Get-Date.

Unbenannt.PNG

We have now unintentionally arrived at objects and attributes. That is not part of this post, it will come at a later stage, but why not play with it? I promised to start at the very beginning. But now I would like to give you a small foretaste what awaits you in the upcoming parts of this series:

Examples:


(Get-Date -Year 1976 -Month 03 -Date 23).IsDaylightSavingTime()


(Get-Date).AddDays(300)

Review


The examples are a great source to learn PowerShell by learning by doing. They can be displayed by using the online help or by using the examples parameter. To do this run Get-Help Your-Command -Examples


The Full Help

To get the full help run


Get-Help Get-Date -Full

The full help displays the whole help topic. This includes parameters, attributes, and last but not least the examples.

The Detailed Help

Get-Help with the parameter Detailed shows parameter descriptions and examples.


Get-Help Get-Date -Detailed

What have we learned so far?


The full help displays the whole help topic. The detailed help shows detailed parameter descriptions and examples. And once again, I can’t mention it often enough: The examples are the most important.


Help files location

The downloaded help files can be found in

C:\Windows\System32\WindowsPowerShell\v1.0\en-US\

The file name is Microsoft.PowerShell.Commands.Management.dll-Help.xml.

1.JPG

Unbenannt.JPG

This help file can also be displayed in PowerShell:


(Get-Command Get-ChildItem).Helpfile

 

Unbenannt.JPG

Or display the help files with Get-Help. We’ve dealt with Parameters in the third part. Here’s the file about parameters (in C:\Windows\System32\WindowsPowerShell\v1.0\en-US\)


Get-Help about_Parameters

Unbenannt.PNG

Review


Help files are located in a specific Windows folder C:\Windows\System32\WindowsPowerShell\v1.0\en-US


 

More about the PowerShell help in the Microsoft Docs: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/get-help?view=powershell-5.1

That’s it for today. Hope you enjoyed it! Here is the exercise til next time.

Exercise

Remember our Code of Practice:


Do it yourself. Anything you don’t do yourself will soon be forgotten. 


 

What is the 4th help example of the command start-process? Once you have found it, run it on your computer!

The solution can be found in the next part.

See you at the next article PowerShell for Beginners (Part 5): The Execution Policy (ps1 Files)


Patrick Gruenauer, MVP PowerShell

Categories: PowerShell

Tagged as: ,

2 replies »

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s