PowerShell Parameter Validation Part 2
Let's continue exploring the world of parameter validation in your PowerShell scripts and functions. As I mentioned in the previous article, you can't make any assumptions about how a user is going pass values to your parameters. You can't assume they will always interactively enter a valid value. If a bad parameter value is going to cause a problem later in your code, you want to identify the problem as soon as you can and before any code is executed.
Today, I have a few more common validation tests to cover.
ValidateLength
Use this parameter validation when you want to ensure that parameter value is of a specific length. The value must be a string. You need to specify the minimum and maximum length of the string. Here is an example:
[ValidateLength(3,15)]$Computername = "SERVER23"
In this example, the value of $Computername must be between 3 and 15 characters long. If the value is less than 3 or more than 15 characters, PowerShell will throw an error.
PS C:\> $computername="aa"
MetadataError: The variable cannot be validated because the value aa is not a valid value for the Computername variable.
If you want to specify a fixed length, you can use the same value for both the minimum and maximum length.
Function Test-String {
[CmdletBinding()]
Param(
[ValidateLength(10,10)]
[ValidateNotNullOrEmpty()]
[string]$Text
)
Write-Host "Testing $Text" -foreground yellow
}
In this example, the value of $Text must be exactly 10 characters long.
PS C:\> Test-String abcdefghki
Testing abcdefghki
Any other length will throw an error:
PS C:\> Test-String abcdefghkis
Test-String: Cannot validate argument on parameter 'Text'. The character length of the 11 argument is too long. Shorten the character length of the argument so it is fewer than or equal to "10" characters, and then try the command again.
PS C:\> Test-String abcdefghk
Test-String: Cannot validate argument on parameter 'Text'. The character length (9) of the argument is too short. Specify an argument with a length that is greater than or equal to "10", and then try the command again.
If you want to test the length of an array, use [ValidateCount()] which I covered last time.
ValidateRange
Sometimes, you want to ensure that a parameter value is within a specific range. This is not uncommon with integer values where you need to ensure the value falls within a given range. You can use the [ValidateRange()] attribute for this purpose. Here is an example:
[ValidateRange(1,10)][int]$Days = 5
The value of $Days must be between 1 and 10. Anything else will throw an error.
PS C:\> $days = 20
MetadataError: The variable cannot be validated because the value 20 is not a valid value for the Days variable.
PS C:\>
PS C:\> $days = 1
The range is inclusive, so the value of 1 is valid.
However, you aren't limited to just integers.
PS C:\> [ValidateRange(.1,1)][double]$Percent = .5
PS C:\> $percent
0.5
PS C:\> $percent = 2
MetadataError: The variable cannot be validated because the value 2 is not a valid value for the Percent variable.
PS C:\> $percent = .15
Just remember to use the appropriate data type for the range you are validating.
PS C:\> [ValidateRange("a","d")][char]$Character = "a"
PS C:\> $character="z"
MetadataError: The variable cannot be validated because the value z is not a valid value for the Character variable.
PS C:\> $character="aa"
MetadataError: Cannot convert value "aa" to type "System.Char". Error: "String must be exactly one character long."
PS C:\> $character="c"
ValidateRange Kind
In PowerShell 7, you have an additional option for this validation. You can specify the kind of comparison you want to use.
- Positive
- Negative
- NonNegative
- NonPositive
PS C:\> [ValidateRange("Positive")][int]$Count = 10
PS C:\> $count = 20
PS C:\> $count = -10
MetadataError: The variable cannot be validated because the value -10 is not a valid value for the Count variable.
This example demonstrates that the value of $Count must be a positive integer. A value of 0 will fail Positive and Negative validations. This is where NonNegative and NonPositive come in.
PS C:\> [ValidateRange("NonNegative")][int]$Count = 5
PS C:\> [ValidateRange("NonNegative")][int]$Count = -5
MetadataError: The variable cannot be validated because the value -5 is not a valid value for the Count variable.
PS C:\> [ValidateRange("NonNegative")][int]$Count = 0
This option allows you to include 0 in the range.