Parameters for PowerShell Scripts and Functions

Using parameters for your Scripts and Functions is very powerful. You don’t have to hardcode things in them, making running them from a command line easier. This blog post will show you the parameters I use in most of my scripts and how they work.

Parameters

In the chapters below, I will highlight some parameters that I use frequently. They are stored in the param () section at the top of the script or function, one per line starting with [parameter.

HelpMessage

You can use HelpMessage to supply information about the parameter when the user is prompted to input something. I used the example below for more details on the -FileName parameter. Because it is mandatory, running the script will prompt you to enter a value.

You can see that the scripts prompted for a value for the -Filename parameter, and it also tells you to use !? For Help. Typing !? Shows you the HelpMessage that you configured in the parameter, in this case it tells you to use a complete path to the filename with an example of c:\temp\powershellisfun.txt.

Mandatory

If you need to use a parameter, specify it using Mandatory = $true. If not, then you can use Mandatory = $false. For example:

param(
    [parameter(Mandatory = $true)][string[]]$ComputerName = $env:COMPUTERNAME
)

In the example above, the -ComputerName parameter must be used. However, if no value is specified, it will automatically use $env:COMPUTERNAME as the value. If you don’t use the -ComputerName parameter and the Mandatory option is set to $true, it will automatically use $env:COMPUTERNAME.

Specifying the -ComputerName parameter will prompt you for the value when running the script. Also, if you configure the variable $ComputerName as a string using [string], you can add [] before the last bracket so that it accepts multiple values.

Running this example will look like this:

You can see that running it without the -ComputerName parameter automatically outputs your local computer name as a value. If you specify the -ComputerName parameter, you can use one value (TEST-123), and it will output that. But if you use two values made possible by using [string[]], it will return two (TEST-123 and TEST-456).

ParameterSetname

If you have multiple parameters and a few that can’t be used together, you can use the ParameterSetName option. In the example script below, I have the -PowerShellEventlogOnly and -PSReadLineHistoryOnly parameters that can’t be used together. If you run the script and use the – key with Tab to show the parameters, they will show both. If you select one, try to choose the other. Then, you will see that it’s no longer available for usage.

You can see that when I first pressed – followed by Tab to display all the parameters, both the PowerShellEventlogOnly and PSReadLineHistoryOnly parameters were available. However, when I used the PowerShellEventlogOnly parameter, the PSReadLineHistoryOnly parameter was no longer available.

Switch

Using [switch] in a parameter will set the parameter to $true or $false when specified (Boolean). This can be useful for parameters in which you want something to trigger when used. In the example below, I use it to output the contents of a file in an Out-GridView pane or to screen when not used:

You can see that running the switch.ps1 script with the -filename parameter will display the contents of the powershellisfun.txt on your screen. The -GridView parameter with a $false value will also be outputted on your screen. The -GridView parameter, with a default value of $true, will output the contents in an Out-Gridview pane.

ValidateSet

Using the ValidateSet option, you can specify a parameter with one of the configured values. This is easier than prompting or supplying values that might have typos. In the example below, I used a set of values for the state of a Windows Service that can be passed as a parameter.

You can see that when using the -StartupType parameter, the available values shown are the ones configured in the ValidateSet values. When I tried to type a value not in the list, valuenotinlist, in this case for testing, it threw an error that it’s not in the ValidateSet values. “The argument “valuenotinlist” does not belong to the set “Automatic,Boot,Disabled,Manual,System” specified by the ValidateSet attribute. Supply an argument that is in the set and then try the command again.”

More information

In the chapters above, I showed the parameter options that I use most. You can find more advanced information here.

Wrapping up

In this blog post, I showed you some examples of parameters that you can use in your scripts to make things more dynamic and easier. Hardcoding variables in scripts is not something you should do for scripts that could be used by more people other than you 😉