Next, I want to move to a set of commands,
and you can install this module from the PowerShell gallery.
I have notes in the demo file on how to do that if
you want to follow along here.
So let's say that you have a completely new command
that you've been assigned, told, hey,
we need you to work with these sets of PowerShell tools, but
you have no idea how to use the tool, so you have to use the
help. My tools that I wrote here, that you can work with, are vegetable commands.
So I have a command called Get‑Vegetable, and we're just
going to look at just the parameters for Get‑Vegetable. And
you can see that it has name,
so it will take a single string, notice there's no square brackets,
the name of vegetable, it's not required, it's positional,
which means I don't have to type ‑name, it takes pipeline input, and it
will accept wildcards, RootOnly is a switch, alright,
so those are really the only parameters for that command.
You know what, let's just run it. It's a get command, you
know, what's the worst that can happen? So let's run
Get‑Vegetable, and there we go.
So I get an object, and the nice thing about this command, these vegetable
commands, is they have nothing to do with technology.
You can just focus on the PowerShell concepts without worrying
about the technology underneath the hood, because you don't need
anything other than the commands and they'll create these kind of
fake vegetable objects for you.
Get‑Vegetable works.
Let's go back and try Get‑Vegetable, let's try that
other parameter, that switch parameter.
Remember,
I don't have to type any values after that, just ‑RootOnly is enough, and the
command is designed to only show me vegetables that belong, that are root
vegetables like carrots and turnips and potatoes,
that sort of thing.
Alright, so the help reinforced and told me how to use the command.
Now I also know that the name parameter is positional,
so I should be able to do Get‑Vegetable carrot, and that value
carrot will be assigned to the name parameter, and sure enough,
that works. Now some commands will have mandatory parameters. Let's
look at help for New‑Vegetable.
Now you can't quite tell it in the syntax there,
so let's just quit this here, and I'm just going to do New‑Vegetable by itself.
I didn't type in anything. PowerShell is saying,
hey, New‑Vegetable has a parameter, ‑name, and it is required, it's mandatory,
so it's prompting me to put in some value. See that
little exclamation point, question mark?
If you type that at the prompt there,
if the command is written with a little help message,
you can get that listed there, and then it'll tell you, hey,
what is the name of the vegetable.
So I'm going to go ahead and create, let's create okra.
Oh, let's make it all proper lowercase here, okra. Okra is green,
and I'm just going to make up a UPC code.
Alright, so now I've created a new vegetable.
I had the required parameter, but I was able to handle that just fine.
If we go back and look at help for New‑Vegetable
and look at that name parameter, sure enough,
you can see that it is required.
It's positional, so you don't have to specify the name parameter.
There is no default value, and it doesn't accept wildcards.
Let's look at one more example with my vegetable commands and parameters.
Let's look at Set‑Vegetable.
Alright,
so you can see here there are two parameter sets to use this,
one that allows you to do an input object,
which means, generally when you see that,
that means something is going to be piped into the command.
Or you can specify modifying vegetables by parameters, you can see
there's ‑name and parameters for changing the cooking state and
the number of vegetables and whatnot.
So let's just run help for Set‑Vegetable and look at
all the parameters in more detail.
So CookingState, you can see a little description there.
You can see it's not required.
It's named, which means,
if I want to use that parameter I have to type ‑CookingState, count,
input object, and so on, so you can look at those in
a little more detail on your own.
Let's go ahead and run Set‑Vegetable, and let's modify corn, and let's grill
it, because I love grilled corn. And we'll use ‑passthru,
which tells PowerShell, hey, show me the object that was written to
the pipeline, and there is my updated object,
which I can verify again by running Get‑Vegetable using the
positional parameter corn, and there we go, so that all works. Even
though I had no idea, and you have no idea how to use these commands,
by taking the time to read the help,
It will tell you what you can expect and how you can use the command.
I know we're just getting started with PowerShell, but at least let me
give you a taste of this idea of pipeline and object in the pipeline,
because I want to make sure you can kind of understand what this looks
like in terms of the help documentation.
So if I look at my vegetable command and look at the name parameter
again for Get‑Vegetable, we see, just to reiterate here,
this will accept pipeline input,
meaning I can send stuff into this command and it will take it by
value or by property name. By value, again, means if I see
something, a thing like a string or a word,
I'm going to assume that must be the name of a vegetable. By property name
means if I see an object, and if the object coming in has a name property, or
to be clearer, a property called name, I will then take that value from the
object and assign it to the name parameter, because the name parameter matches
the name property on the object.
Those two things go together,
and so the values just kind of get piped and passed on through.
So, let me show you this, now that you can kind of see that the help says,
hey,
this should work. So I should be able to get content on a list of vegetables
that I have in my work folder and pipe them to Get‑Vegetable. PowerShell under
the hood is going to go through that list and say,
hey, I see the first value is carrot,
so I'm going to assign that to the name parameter.
I'll do that again for broccoli and then cauliflower,
and so Get‑Vegetable gives me the results that I am expecting
from reading in that list of vegetables from the text file. To
make sure you really understand this, let's try something that's going to fail.
So I'm just going to get a list of shares in a text file I have here,
and I'm just going to save this to a variable $list so I don't have to rerun
the Get‑Content, and just so you can see what is in $list.
Alright,
so I'm looking for shares on my computer called work, scripts, and reports.
Now I have this command Get‑SMBshare, and we can look at help real quickly.
You can see that there is a Name parameter. So I'm not even going to dig too
far into it, let's just say I glanced at the help and go,
okay, I should be able to maybe pipe $list to Get‑SMBshare,
and I should be able to get all the shares that match those names in that list.
No I don't.
I get a bunch of error messages. Now, just so you know,
I changed the color of the background error message so that
it would be easier to see on the screen.
Get‑SMBshare is giving me errors that says,
hey,
the input object cannot be mapped or bound to the parameters of any command,
and I get that three times because it's trying to do that for each thing
that is getting piped in. And I may be thinking,
well, why doesn't that work?
I mean, it worked for Get‑Vegetable, why doesn't it work for Get‑SMBshare?
This is why you need to read the help.
So I go back now and look at the Name parameter.
You can see that it will take names as a collection of strings,
but it does not accept pipeline input by value,
which is what I was trying to do.
It will take it by property names.
So what that means is if I were to do import csv, and if I have a CSV file that
has the names of the shares, then that I can pipe into Get‑SMBshare and that
works, and I get an error for reports because that share does not exist on the
computer, and that's kind of what I want to see here anyway. You can take a
look at data.csv if you want to see how that file is structured. Import csv is
reading the CSV file and creating an object with the header names as the
property names.
There is a property called Name,
so PowerShell says, hey, this command can take input by property name, and
so I'll take that name property of the incoming object, assign it to the
parameter value, and then the magic happens.
That is the power of the pipeline,
and you may need to refer to the PowerShell help to understand
why it may or may not be working in your work or the things
that you are trying to get done. So with that, let's go back to the slides and wrap up this lesson.