Up next in 10
Take different actions with PowerShell parameter sets! Learn how to define parameter sets and how they impact your script execution.
How to Write Awesome Functions with PowerShell Parameter Sets
https://jeffbrown.tech/how-to-write-awesome-functions-with-powershell-parameter-sets/
Chapters
00:00 Introduction
00:15 Parameter Set Documentation Example
01:06 Define Parameter Sets
03:50 Set Default Parameter Set
05:21 Determine Parameter Set Usage
08:34 Another Parameter Set Example
11:00 Summary
Show More Show Less View Video Transcript
0:00
What's up, everyone
0:00
Today we're going to continue talking about parameters with a really neat feature called
0:04
parameter sets. This allows you to specify specific groups of parameters depending on how you want users to input data into your script
0:14
Let's go ahead and get started. I want to get started by showing a quick example of parameter
0:17
sets, and you may not have even known you've seen them before
0:21
We'll take an example command here, new mg group member. If you notice under the syntax section here
0:28
there are multiple examples of using this with different parameters. These are essentially parameter sets
0:34
You notice in the first one here you have group ID. But if you notice in the second example
0:39
there's group ID and then body parameter. But if you go back and look at the first one
0:43
there's no body parameter defined there. And then if you look at the third example
0:47
there's input object, but there's no group ID, no body parameter. This is just showing you the different scenarios
0:54
you would use different parameters with each other, and these are defined through parameter sets
1:00
So let's go ahead and switch back to my example script, and I'll show you how to define these in your own scripts
1:06
Here we have a script called add group members. This is going to be a custom script
1:10
that we can use to add a user to a group based on the group's
1:15
name or the group ID. Maybe this is calling out to a database
1:19
to add them or some other API call, or maybe you're just making your own custom group member
1:26
PowerShell script here. We have three parameters like I just mentioned, group name, group ID, username
1:32
They're all strings. They're all mandatory. And then down here at the bottom
1:35
we're just outputting those values as we go through it. If we were to go ahead and run this
1:42
I have a previous example here. I've got the username, the group name, and the group ID
1:47
and that outputs all of those. But this is a little bit redundant
1:51
If we have the group name, we can use that, or if we have the group ID, we can
1:55
use that to add this user account to that group. Basically, there's no need to ask for both of them
2:01
if you run the script. You want to allow your user running the script
2:05
to use one or the other, depending on which piece of information they have
2:09
Let's set both of these into their own parameter sets now. We get started by doing that by going into our parameter
2:16
attribute section here. Should be familiar with this. We've got it mandatory set to true
2:20
And actually, that's a bit redundant. So let's go ahead and get rid of that
2:25
And we'll start typing parameter set name. And this is where we can define a parameter set
2:29
that this is going to belong to. And we just put in the name of our parameter set
2:34
In this case, it's going to be name for group name. And we'll do the same thing here
2:42
This is going to be our ID parameter set. Now, username is going to be a part of both parameter sets
2:50
So we don't need to do anything with defining parameter set for it
2:54
If you have parameters that are going to be involved with all the parameter sets
2:58
you just leave its definition as is. We have our updated script here
3:02
We'll go ahead and save it. And let's go ahead and try this again
3:09
Let's bring our previous command up here where we use both group name and group ID
3:13
And we're going to run into an error, just saying we can't resolve our parameter set using
3:18
these specific parameters. One or more of them cannot be used together
3:22
Or maybe there is a parameter set and you didn't use all the parameters that
3:26
are defined in that set. So let's back up. We'll clear the screen
3:32
And let's just use one of these here. That's expected. We see the group name, but not the group ID
3:38
because that's not part of the parameter set. We didn't define its value
3:43
Let's go back and go group ID. And we'll put a random ID in here
3:47
And same thing, we don't have the group name because we didn't use that parameter. Right now, if we were to just run this with the user name
3:54
let's back up a little bit here, it's going to come back and tell us, again, that same error
4:00
We either didn't provide enough parameters or we're using parameters that aren't supposed to be used together
4:04
In this case, we did not define enough parameters. One thing you can do is define a default parameter set
4:12
And that's what we need to do here. And this is going to set the preferred method
4:16
or the preferred parameter set name you want people to use if they don't specify it initially
4:23
We can do this by adding the cmdlet binding attribute up here
4:27
The cmdlet binding attribute just adds attributes to your functions or script
4:32
that make them act like compiled cmdlets. And it just provides access to features
4:37
you would see in normal cmdlets. And one of those being we can define a default parameter set
4:44
So inside of here, let's go ahead and do this on a new line
4:47
We'll say default parameter set name. And we'll set it to the name of, we'll do, let's do ID here
4:56
We're just saying our default parameter set name is going to be ID
5:00
We'll save that. Clear out the screen. And now if I go back and run this
5:06
without group name or group ID, it's going to prompt for group ID
5:10
That's the default parameter set. It's also a mandatory attribute. And we're good to go now
5:16
So we'll punch in some value here. There we go, same output we saw before
5:21
Now inside of your script, depending on which piece of information is presented
5:26
maybe you want to take different actions. Maybe you're calling an API that has a different call
5:32
to make based on the group name or the group ID to add this person to the group
5:38
Within the scripter function, you can identify which parameter set is being used
5:43
and take different actions and code different logic, depending on which one's being used
5:48
Let's get a little bit more room here. We can do this using the automatic variable ps cmdlet
5:57
And it has a property called parameter set name. Let's actually take a quick look at what that looks like
6:03
I'm going to comment this out. And right here, we're just going to run ps cmdlet
6:08
It's an automatic variable. You don't have to define it or anything. Let's save that
6:15
And let's bring back up a previous command here. We're outputting ps cmdlet here
6:22
And you can see right here, it shows the parameter set name is ID
6:27
So we can use that to identify which parameter set is being used. Let's get rid of this and uncomment this
6:39
You can use lots of different ways to identify the parameter set name
6:43
You can do an if statement. If the ps cmdlet parameter set name equals this
6:48
do this or do that, else, whatever you want to do. In this case, I'm using a switch statement
6:54
So I'm going to switch on the parameter set name and show here if it's name
6:59
We're going to write host, use the name parameter set, ID, and just write out, use the ID parameter set
7:06
Let's do one better. Let's get rid of write host here. So let's save that
7:15
We'll bring this back up. We'll rerun this command again. You use the ID parameter set. Perfect
7:23
We'll bring back group name. You use the name parameter set. Perfect
7:27
So we're correctly identifying which parameter set is being used. And in this way, we could maybe also modify our output
7:36
So let's take right here. We'll take group ID user name. Just output this right here
7:47
And instead here, we'll put that. And let's get rid of this down here
7:59
Now it's only going to output either the group name or the group ID, depending on which parameter we used
8:05
and then the user name. Bring this back up here. Let's clear the screen
8:11
Let's go back and run group name first. Perfect. We use the name parameter set
8:16
We don't see group ID in here. And if we go back to group ID, use the ID parameter set
8:21
and we don't see the group name. Just showing how you can introduce some logic
8:26
to figure out which parameter set is being used. So then you can only focus on those parameter values
8:32
inside of that part of the script. In a previous video, I went over parameter validation
8:40
We went through a couple of validation techniques inside of our new voter registration script
8:46
One of the things we had in here was we had date of birth or age
8:51
This is a perfect scenario to use parameter sets. Maybe the person writing it, they
8:57
can provide the date of birth, or they provide the age just to determine if the person is of age to register to vote
9:05
Let's go back up here. We've got mandatory. We'll do parameter set name equals date of birth
9:14
Same thing down here. It's mandatory. Parameter set name equals age. And let's go up here and add our commandlet binding attribute
9:26
And we're going to say the default parameter set name equals we're going to prefer date of birth
9:32
because that actually does some calculations to verify they are of age instead of just taking their age at face value
9:40
And same thing, we can update our output here. So let's go down and let's do a switch statement
9:47
PS commandlet parameter set name if it's date of birth. We'll take the first top half of this year
10:05
And then if it is age, do some formatting here
10:17
Take that guy out. And instead of date of birth, we'll do age
10:24
We'll go ahead and save that. I think that should be pretty good to go
10:30
So let's bring this up here. The new voter registration. Got our history here
10:39
So let's go back and just do date of birth. Perfect, so that showed just our date of birth entry there
10:47
Or if we go back and do dash age, we'll say 28
10:54
And that outputs a different voter registration. Doesn't show the date of birth, shows the age, and so on
11:01
That does it for this video. Hopefully you learned a little something about parameter sets
11:05
and how you might be able to use them in your scripts just to dynamically change which parameters are available
11:11
so they make the most use and the logic in your script of what you're trying to accomplish
11:15
And we went back and updated our new voter registration script here to either use date of birth or age, but not both of them
11:23
Thank you for watching and we'll see you next time
#Programming
#Programming
#Scripting Languages