PowerShell How-To

Getting Input into Your PowerShell Functions with Parameters

Here's a quick walkthrough of how to build function parameters in reusable snippets.

If you are building PowerShell longer than a few lines, it is good practice to break up your code into reusable snippets. This way you can only call the code snippet over and over instead of duplicating code in many places. One way to do this is to build functions. A function has three general tasks it can perform; it optionally takes an input, does some processing and optionally sends something out.

In this article, I'd like to go over a few different ways in which you can provide input to your functions. To do this, we are going to go over how to build and use function parameters.

At it is most basic, a PowerShell function looks something like this:

Function Get-Something {

}

The function has a name and a couple of braces to include the code that makes up the function. It technically works but it's not too useful. For it to do something, we have to add some code inside of it.

Function Get-Something {
Write-Output 'I am in the function now.'
}

This would then output something like this:

[Click on image for larger view.]  Figure 1.

This works but there's a problem here. This is all that function will ever do. There's no way to customize what goes into that 'I am in the function now' text. I'd like some way to customize that depending on some kind of criteria. To do that, I'll need to use a variable in that string somewhere.

Function Get-Something {
Write-Output "I am in the function now. My variable is $VariableHere"
}

You can see that I've replaced the single quotes with double quotes to expand my new variable and included a $VariableHere variable inside.

I run it again but it doesn't work as expected.

[Click on image for larger view.]  Figure 2.

The reason is that $VariableHere doesn't have a value. We need a way to get a value to it. The best way to do that is through a function parameter. By including a parameter into our function, we can pass a value to $VariableHere at the time the function is executed allowing us to customize what the string says.

I'll go ahead and create a parameter called $VariableHere. In PowerShell, I can do this two different ways. I can either include the parameter in parentheses on the same line as the function name like this:

Function Get-Something($VariableHere) {
Write-Output "I am in the function now. My variable is $VariableHere"
}

Or I can create a param block and include the parameter that way.

Function Get-Something {
Param($VariableHere)
Write-Output "I am in the function now. My variable is $VariableHere"
}

I recommend the latter approach as this gets you in the habit of specifying how parameters are declared in advanced functions. The functions we are using here are called "basic" PowerShell functions. If you haven't already built advanced PowerShell functions yet, I encourage you to learn as they include much more functionality. An excellent resource is my Pluralsight course entitled Building Advanced PowerShell Functions and Modules by yours truly.

Now that we have a parameter, we can pass a value to that parameter.

[Click on image for larger view.]  Figure 3.

You can see that I can specify the parameter while I'm calling the Get-Something function with a dash and the parameter name followed by the parameter value. This then gets passed into the function and expanded in the string to then get output to the console as you can see above.

About the Author

Adam Bertram is an independent consultant, technical writer, trainer and presenter. Adam specializes in consulting and evangelizing all things IT automation mainly focused around Windows PowerShell. Adam is a Microsoft Windows PowerShell MVP, 2015 powershell.org PowerShell hero and has numerous Microsoft IT pro certifications. He is a writer, trainer and presenter and authors IT pro course content for Pluralsight. He is also a regular contributor to numerous print and online publications and presents at various user groups and conferences. You can find Adam at adamtheautomator.com or on Twitter at @adbertram.

comments powered by Disqus

SharePoint Watch

Sign up for our newsletter.

I agree to this site's Privacy Policy.