Talk Tech to Me: PowerShell Parameters and Parameter Validation

In Talk Tech to Me: How to Write Better PowerShell Scripts, we covered using Try/Catch blocks, using special output formatting and when an error should stop a script versus just notifying you that something didn’t work as intended. Then, in Talk Tech to Me: Help and Parameters in PowerShell Scripts, we talked about adding help, cmdlet binding and parameter sets. In this article, we’ll be discussing the use of sending parameters to your scripts.

A script that never changes and has static values may not need parameters, but to really improve your scripts, you will want to add parameters to allow them to evolve and be multipurpose.

Let’s say we have a script that does three things:

1. Gets the name of a computer
2. Modifies the attributes of that computer in active directory
3. Sends a report through email to a list of users

You can hard code the name of the computer in the script, along with a domain controller, the email server and the recipients of the email in the script.

But what if you want to use that script in other companies or the server names change in the future? You could open the script each time you want to change something, modify the values, save it and then run it. Or, you can add parameters to allow for changes without modifying your script each time.

Param Blocks

Let’s look at a simple script called “Hello.ps1”.

When you run the script, it will simply output the phrase “Hello Bob.” and that’s all it will do. But what if you want to change the name to someone else? You would have to open the script and manually change the name to something else. Wouldn’t it be easier to add a parameter that would accept another name to say hello to?

By adding a block of code at the top of your script called a param block, you can add a parameter to pass into the script.

This will allow the script to say hello to whatever name you pass into it.

Let’s add some hidden messages by changing our “Write-Output” to “Write-Verbose” and see what happens.

As you can see in the output, our message never gets displayed, no matter what we do. We can view the verbose message by adding something called “CmdletBinding” at the top of our script.

According to the help for “CmdletBinding”, it makes [functions and scripts] operate like compiled cmdlets that are written in C#, and it provides access to features of cmdlets. Adding “[CmdletBinding()]” at the front of our script will give us access to advanced features.

Now my message can be displayed.

Declaring Parameters

Let’s put that into perspective in a real-life script. Most people don’t care about the details of the script, just the result. But for testing and troubleshooting, I like to see all the steps during a script: success messages from Try/Catch, details of files, counts of results, steps during loops and so on.

We can now start to get fancy by declaring what the parameter should be. So far, the parameters have always been unspecified. But we are going to change our code a little and try some basic math.

Greatness! It worked, but what if someone gives me a word instead of a number?

Well, not what I expected, but that might be useful for other purposes. Rather, I’d like the script to tell me that $First and $Second should be numbers, not a string or some other type. By declaring the variable type in the param block, I can force users into better inputs.

In the example above, the first time I ran the script, I made sure that the variables, “First” and “Second” were integers. The second time I ran the script, I changed the named parameter “First” to the word “Alpha”, which my script did not like and told me so in a descriptive error message. Making sure to declare the variable type in the param block will ensure that your expected variables are of the type you wanted.

Checks in Parameters

You can also add more detailed checks to your parameters. In the next image, I’ll show three examples of validating your parameters.

In my script, I declare that the “First” parameter needs to be between the values of 0 and 5 (that also includes the 0 and 5) and that the “Second” parameter needs to be one of three values, 2, 4 or 6.

The first time I ran the script, everything worked as expected. In the second example, I intentionally made the “First” parameter too large. In the third example, I fixed the “First” parameter, but the “Second” is still wrong.

You can see how getting very specific with parameters can be useful.

Default Values for Parameters

The last thing I want to talk about is setting default values for your parameters. You can set a default parameter and assume that is the value being passed in, or you can change the parameter’s value by manually typing in the new value when you run the script.

As you can see above, the default value for “ComputerName” is “Server01”. But that doesn’t mean that I always want to force the script to be “Server01”. I can change the value of the parameter each time I run the script.

In my “Hello2.ps1” script, I declared the parameter “ComputerName” to be an array. By doing so, I turned this into a tool that can run against a single computer or multiple computers. I can now try to work on multiple computers without having to open the script and make changes to the code each time I want to change the computer name.

Microsoft’s help documentation shows very good information about these and can be found by typing “Get-Help about Parameters” and “Get-Help about Functions Advanced Parameters”. If you get errors, when you run those commands, you will need to update your help files. Running with elevated privileges, in PowerShell, run the command “Update-Help -Force” and that will update all your help files.

So now you can see how adding parameters and validating their input could help improve the expected results of running your scripts. It really allows you to change the purpose of the script without having to open the code each time and modify static parameters.

In the next article, I’ll be talking about regions and comments within your scripts. Making your scripts “pretty” is really important when you go back later to troubleshoot or you are trying to read someone else’s code. I’ll demonstrate a script with regions that I wrote for real-world use and discuss why regions are helpful when reading code.