Powershell functions can be created as advanced functions. These functions behave very similarly to built-in Powershell cmdlets. Because I can't do without the ability to add a -Verbose or -Debug parameter to my functions now nowadays, these are the only kind of functions I build. Advanced functions, just like "dumb" functions, have parameters. The parameters are the values that are passed into the function from your script.
Good script functions always include some kind of data validation. Data validation, in general terms, is simply ensuring that what you pass to your function is what you expect. For example, let's say I have a function put a True or False value in a file. You ONLY want the words True or False in there. If it's not True or False then some other process you've got that reads this file will blow up and your whole company will implode. This is for the future of your company, dammit!
Therefore, we've established this has to be True or False. How do we do that? Well, let's say you've got a function like this:
[powershell]
function Set-SomeTrueFalseValue ($Value) {
Add-Content C:\somefile.txt -Value $Value
}
[/powershell]
..and you call that function like this:
[powershell]
Set-SomeTrueFalseValue 'ImplodetheCompany!!!!'
[/powershell]
What do you think this is going to do? If you've passed Powershell 101, you'd know that function would have written 'ImplodetheCompany!!!!' to that file which, because of your True/False requirement, would, in fact, do just that. How do we prevent that? Enter Powershell parameter validation.
Powershell's advanced function parameter validation is extremely cool and useful! It will prevent anything you don't want passed to that function no matter how complicated of a requirement you want to create. In our simple example, we only want a string value of either True or False. Let's see how you'd do that.
[powershell]
function Set-SomeTrueFalseValue {
[CmdletBinding()]
[OutputType()]
param (
[Parameter(Mandatory)]
[ValidateSet('True','False')]
[string]$Value
)
Add-Content C:\somefile.txt -Value $Value
}
[/powershell]
Now with only a few lines of additional code, I've first created an advanced function from my previous "dumb" function AND I've added some data validation in there. The part where I'm ensuring that only the values True and False will be passed into the script is here:
[powershell]
[ValidateSet('True','False')]
[/powershell]
This is simply saying for the $Value parameter: ONLY allow a string value of True or False. It will then never allow anything else to be passed as $Value into the function. Pretty cool, right? In this example, I'm using the ValidateSet() method, but there are plenty of other ways that you can read about. However, ValidateSet() will be the topic of the rest of this blog post.
ValidateSet() is a function validation method that allows you to specify any number of elements that can be used as values for the function parameter. If I wanted, I could have done something like:
[powershell]
[ValidateSet('True','False','Mom','Dad')]
[/powershell]
...and I could have written the strings as Mom or Dad as well as True or False to my file. It's simply a set of values. One of the cool features about using ValidateSet() with your Powershell functions is that you get built-in tab-completion when you're in the Powershell console. Let me show you. Take a look at this "video". I just pasted in that function into the Powershell console so that I have it available. I then type out what I want and prepare it for execution. You can see that after the Value parameter it's alternating back and forth between True and False. This is ValidateSet() in action. Powershell knows the only thing you can type in there is True or False so it allows you to nicely hit tab until you scroll through all your options.
