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.

• By Adam Bertram
• 04/07/2016

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:

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.

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.

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.