Hello, and welcome back.
We're in the middle of learning about how to get the
most of the PowerShell help system.
In the last module,
I should you had update help and start getting help from PowerShell.
Next, I want to teach you how to interpret what you find.
The better that you can read help, the more you can get out of it,
and the easier I think it will be to figure out why a command
doesn't work the way you think it should.
Alright, so let's get to it.
Here's the first part of help for the Get‑Service command.
The NAME, SYNOPSIS, and DESCRIPTION should all be self evident.
I want to focus on helping you decipher all this stuff under SYNTAX.
These are the different ways that you can use the command.
The first thing I want to point out is that based on the help,
I can see that there are three different way to use Get‑Service.
Under SYNTAX , you can see three different groupings of parameters.
These are referred to as parameter sets.
Each set shows the name of the command, Get‑Service,
followed by a collection of parameters.
Now these collections are unique.
Although some parameters can appear in multiple parameter sets,
there's usually something in each set that makes it unique.
You can't mix and match parameters, that's very important.
If you try to run Get‑Service using both ‑Name and ‑DisplayName,
you'll get an error saying that PowerShell can't
figure out which parameter set to use.
All parameters in PowerShell start with a dash.
So we have ‑DependentServices and ‑DisplayName.
Following the parameter name is an indication of
what type of valve you you can use.
Now everything in PowerShell is a type of object.
After a DisplayName,
you can see that PowerShell is telling you that it can accept strings.
Now a string is just a fancy way of saying text.
The double square brackets after the type name indicate that the
parameter will take a collection or group of values.
Typically, these are separated by commas.
Based on the help,
‑DisplayName will let me specify a group of service display names,
again separated by commas.
Another type of parameter is a switch.
Look at that ‑RequiredServices.
There's no value after it.
It switches like an on/off switch, or you can think true/false.
If you use the parameter name,
then the command's code will handle the rest of the operation,
you don't have to do anything else.
Now I'll tell you this because eventually you're going to
come across commands that have parameters that feel and look
like they should be switches, but for some reason,
the person or team that wrote the command,
they want you to specify true or false.
The new ADUser command is a good example.
It has a parameter called ‑Enabled, which you can use to enable the account.
Now I think it should be a switch,
and all I should need to do is just run ‑Enabled,
but nope, I have to type ‑Enabled $true.
When you look at the help, you'll see that the parameter wants a boolean value.
That's why you need to read the help and not make any assumptions.
The last thing to cover is the square brackets surrounding parameters.
This indicates the item in brackets is optional.
You don't have to use ‑DependentServices or ‑Include,
but if you want to use ‑DisplayName,
you have to type the parameter name because it is not in brackets.
Now compare that to the ‑Name parameter.
The entire parameter is optional, and if you want to use the parameter,
you don't need to type ‑Name.
The parameter name is optional.
This is referred to as a positional parameter,
and I'll come back to this in a few minutes.
In meantime, here's another example.
Here you can see the help for Get‑Process,
and you'll notice that the ‑Id parameter is not in brackets,
meaning you have to type the name if you want to use it,
and it can accept a collection of Int32 types,
or integers.
And how do I know that?
See that double square brackets?
That's how we know.
‑IncludeUserName is a switch and doesn't need any values.
So how about a pop quiz.
Looking at that help,
do you think that you can use ‑IncludeUserName and
‑FileVersionInfo in the same command?
No, of course not.
There is no parameter set that includes both parameters.
If you tried that, you'd see the error message,
Parameter set cannot be resolved using the specified name parameters.
One or more parameters issued cannot be used together or an
insufficient number of parameters were provided.
So PowerShell tells you very clearly, hey,
I have no idea what you're trying to do because you're
trying to mix and match parameters.
By the way, the common parameters that you see there,
and we saw it with the help for Get‑Services as well,
that's really a placeholder for a set of parameters that all cmdlets have.
These are parameters like ‑Verbose or ‑ErrorActionPreference.
You will learn more about those as you learn more about PowerShell.
We really won't get into them in this course.
Or if you want a little exercise, to try this.
See if you can find a help topic that explains how to use them,
or what they're all about.
Otherwise,
let's dive a little deeper and look at a few
specific parameters for Get‑Process.
Sometimes you need to get a bit more detail about a parameter
than from what you can see under SYNTAX.
The help command lets you specify one or more parameters,
and you can use wild cards.
This is the same information that you see when you
run help with the ‑Full parameter.
Now uses this technique all the time when I need to
look at a parameter and more detail.
Now here you can see that Id is Required.
Under Id, see Position?
The Id parameter is defined as named.
This means you have to type the name of the parameter,
or at least enough of the parameter name so PowerShell can
figure out what parameter you want to use.
Or, if you look at the SYNTAX, you'll see that ‑Id is not in square brackets.
That's another way that you'll know.
Now you can't just type Get‑Process 123 because PowerShell won't know
that you want the Id parameter to use the value 123.
You have to type Get‑Process space ‑Id space 123.
Compare this to the Name parameter.
This has a position of 0, meaning the first position.
If you type Get‑Process space Notepad,
PowerShell will assign Notepad as a value for the ‑Name parameter.
Some commands like Get‑Service and Get‑Process have default behaviors.
You don't have to specify any parameters or values.
If the command does have a required parameter, you'll get prompted.
If you aren't sure how to use the command, well, you know, just run it.
Of course not in a production setting.
In the help there,
the pipeline input setting tells you how the command will
process objects piped into the command.
Now we won't get into this in great detail in this course,
although I will give you a taste of this in the demo.
And the last thing I want to point out is the Accept wildcard setting.
This should indicate if you can use the *wildcard with
the value Id doesn't use wild cards, but ‑Name does.
One thing to be aware of is that the value may not always be accurate.
A lot of the help content is auto generated and then polished up by a
human writer, but mistakes can happen; however,
don't spend a lot of time worrying about all of this.
It never hurts to try a parameter using a wildcard.
If it doesn't work, you'll just get a message saying that it won't work.
You can verify then by looking at the help to see, oh, yep, I'm
right, that doesn't use a wildcard, or oh,
it does use a wildcard.
So you can see here in the help if it will or not, but sometimes
you just have to try it just to know for sure.
The more you look at help, the easier all of this will be.
And when I say look at help, I mean diving down to this level of detail.
Don't just glance at the SYNTAX and expect it to make sense because it probably won't until you have much more experience with PowerShell.