How To Use Dynamic Parameters in PowerShell Functions

In this video tutorial, PowerShell expert Brien Posey discusses dynamic parameters in PowerShell functions, a technique that enhances flexibility and efficiency. He explains the conventional way parameters work before demonstrating how to use dynamic parameters, highlighting differences between passing a single parameter and multiple parameters of different types.

The following transcript is lightly edited for clarity and length.

Transcript:

Brien Posey: Hello, greetings and welcome. I'm Brien Posey. In this video, I want to show you one of the more advanced PowerShell concepts. It involves using dynamic parameters in a function.

How Parameters Normally Work

Before I get to that, I want to review how parameters work. What you can see on the screen right now is a function demo script that I created. The script is super simple.

If you look at the main body, you can see that we begin by setting a variable called $Number, and I'm setting that equal to 10. The next thing I do is use a Write-Host statement, and I output the value of the $Number variable. So, you'll see a message saying the original number was 10. Next, I declare a variable called $Result, and I set that equal to Add-Two. Now, Add-Two is the name of my function. And I pass, as a parameter, a -number. That number is contained in the $Number variable.

Related:How To Use GitHub PowerShell Copilot via PowerShell Module

$Result = Add-Two -number $Number

So, when this line of code executes, the function (Add-Two) gets called.

Now, here's the important part, we have a section called param. This param section identifies all the parameters that are going to be used by the function. We only have a single parameter in this function. It’s an integer, and it's called $number.

So then, beneath the params section, we have a section that adds a value of two to the value passed to the function. Here we have:

$Result = $Number + 2

So, if we're passing a value of 10 to the function, then we're going to add two to it, giving us a result of 12, which will be stored in the $Result variable. Then, we return the $Result variable to the main script body. The last line of code gives us:

Write-Output “The value returned by the function was: $Result”

We should see a message saying that the value returned by the function was 12.

I'll go ahead and run the script. Let me switch over to PowerShell. I'll go ahead and run the function. You can see the original number was 10. The value returned by the function was 12.

So, that's what the sample script does.

How Dynamic Parameters Work in a Function

Now that I've shown you a basic demonstration of how functions work, let me go ahead and load my other script. I'll show you how dynamic parameters work within a function.

Related:PowerShell Error Handling: Learn These Key Techniques

Now, this script is a bit more advanced than the one that I just showed you. We have our main script body. What I wanted to point out is that Get-Example is the name of my function. This is a function call. Like the function in the example script that I showed you a moment ago, we have parameters that we're passing to the function. However, there are two key differences.

The first of those differences is that this time, I'm passing two parameters instead of just one. The other difference is that the parameters that I'm passing are of different types. So, we have -Type Server, and then -Type Client. And then we have -ServerName “Server01”, and -ClientName is “Client01”.

Let's look at how this function works. Let me go ahead and scroll up to the top. Here we have our function declaration:

Function Get-Example

Then we have our [CmdletBinding()]. And then here's the param section.

Now, this is where things get interesting because first, we have [Parameter(Position = 0)]. So, we're looking at the very first position in the parameter that's passed to the function. And we're starting by doing a validation. You can see ValidateSet. We want to make sure that the first parameter that is passed to the function is set to either “Server” or “Client”. So, we're just doing some error-checking right here.

Related:PowerShell Modules vs. Dot Sourcing: Which Approach Is Better?

The next thing that we have is a Type declaration for the parameter that we're passing to the function. So, we're passing a [string] calling it $Type. If I scroll down, you can see that indeed, we are passing a -Type to the function. We're setting the Type equal to Server, or we're setting the Type equal to Client. So, we're passing either the word Server or Client to the function. That's what this error validation was: It's ensuring we did indeed pass either the Server or Client.

Then, we get into dynamic parameters. You can see that I have a section right here called dynamicparam. What we're doing is starting by setting up something called $paramDictionary, and we're setting that equal to New-Object. The object is a type: System.Management.Automation.RuntimeDefinedParameterDictionary. Then, I’ve created a variable called $attributes. And again, we're creating a New-Object and setting it equal to System.Management.Automation.ParameterAttribute. And then I'm setting $attributes.Mandatory equal to $true.

So then, if I go down a little bit further, we have:

if ($Type -eq ‘Server’) {

What we're doing is we're setting a variable called $dynamicParam, and we're setting that equal to New-Object. The object type is System.Management.Automation.RuntimeDefinedParameter. And we're creating a parameter called ‘ServerName’. And that's going to be a [string].

The next thing that we're doing is we're adding the server name as a dynamic parameter to our parameter dictionary. Then, I have a line that says “if the type is set to Client,” instead of “set to Server.” Then, we're doing the same thing, except the parameter that we're adding is ‘ClientName’ rather than ‘ServerName’.

So, we're essentially defining parameters on the fly as a part of this function. And we're adding either ‘ServerName’ or ‘ClientName’ – but not both – to the list of parameters for this function. Then, we're returning the $paramDictionary.

Then we get to the process section. Now, this is our function body because we're done assigning parameters at this point. In our function body, we have:

Process {

if ($Type -eq ‘Server’) {

$serverName = $PSBoundParameters[‘ServerName’]

Write-Output “Processing server: $servername”

So, you'll see a message saying, “Processing server,” and then the name of the server that we are processing. Because if you look at the function call, you can see we've set the -Type to Server and then pass the -ServerName. The -ServerName is “Server01”. So, if this line of code (Write-Output “Processing server: $servername”) executes, you'll see a message saying, “Processing server: Server01.”

Beneath that, we have:

} elseif ($Type -eq ‘Client’) {

Then, we're doing the same thing, except we're processing a client. We're displaying the $clientname rather than seeing a message that says we're processing a server and displaying the server name.

So, with that said, let me go ahead and run the script.

Once I do, you can see the messages, “Processing server: Server01” and “Processing client: Client01”.

Conclusion

Now, obviously, there are easier ways to do this, but the point was that we were able to create a function that uses dynamic parameters, as opposed to using a static list of parameters. The reason why we might want to do that in the real world is simply because it makes the functions more versatile. In this case, we've created a single function that can handle servers and clients, as opposed to needing one function for servers and a separate function for clients.

So, that's how you go about creating dynamic parameters in PowerShell.