PowerShell Scripting with [ValidateSet]

Today we'll continue our exploration of the parameter validation attributes you can use in you PowerShell scripting. We've already looked at [ValidateRange] and [ValidateScript]. Another attribute you are likely to use is [ValidateSet()]. You can use this to verify that the parameter value belongs to a pre-defined set.

To use, specify a comma separated list of possible values.

[ValidateSet("Apple","Banana","Cherry")]
[string]$Fruit

If the person running the script specifies something other than "Apple", "Banana", or "Cherry" as a value for -Fruit, PowerShell will throw an exception and the script will fail to run. And in case you were wondering, this is not case-sensitive.

If you are going to use this attribute, I recommend providing documentation either in comment based help and/or as part of a help message so the user knows what values to expect. The PowerShell help system doesn't automatically detect this attribute and use it in syntax display as you might have seen with other cmdlets.

Here's a more practical example.

#requires -version 2.0

Param (
[Parameter(Position=0)]
[ValidateSet("System","Application","Security","Directory Service","DNS Server")]
[string]$Log="System",
[ValidateRange(10,1000)]
[int]$Count=100,
[Parameter(Position=1,Mandatory=$True,
HelpMessage="What type of export file do you want to create? Valid choices are CSV, XML, CLIXML.")]
[ValidateSet("csv","xml","clixml")]
[string]$Export,
[ValidateNotNullorEmpty()]
[string]$Path="C:\Work",
[string]$Computername=$env:Computername
)

Write-Verbose "Getting last $Count events from $log event log on $computername"
#base logname
$base="{0:yyyyMMdd}_{1}_{2}" -f (Get-date),$Computername,$Log

Try {
    $data=Get-EventLog -LogName $log -ComputerName $Computername -Newest $Count -errorAction Stop
}
Catch {
    Write-Warning "Failed to retrieve $log event log entries from $computername. $($_.Exception.Message)"
}

If ($data) {
    Write-Verbose "Exporting results to $($export.ToUpper())"
    Switch ($Export) {
        "csv" { $File=Join-path -Path $Path -ChildPath "$base.csv"
                $data | Export-Csv -Path $File  
              }
        "xml" {  $File=Join-path -Path $Path -ChildPath "$base.xml"
                ($data | ConvertTo-XML).Save($File)
               }
        "clixml" {$File= Join-path -Path $Path -ChildPath "$base.xml"
                $data | Export-Clixml -Path $File
                }
    } #switch

   Write-Verbose "Results exported to $File"

} #if $data

The script will get recent events from a specified log on a specified computer and export the results. My script will only export from a short list of logs which I'm validating.

[ValidateSet("System","Application","Security","Directory Service","DNS Server")]
[string]$Log="System",

If an invalid value is detected PowerShell will complain.

PS S:\> .\Demo-ValidateSet.ps1 -comp jdhit-dc01 -log dns -verbose -Export clixml

C:\scripts\Demo-ValidateSet.ps1 : Cannot validate argument on parameter 'Log'.
The argument "dns" does not belong to the set "System,Application,Security,Dire
ctory Service,DNS Server" specified by the ValidateSet attribute. Supply an arg
ument that is in the set and then try the command again.
At line:1 char:45
+ .\Demo-ValidateSet.ps1 -comp jdhit-dc01 -log <<<<  dns -verbose -Export clixm
l
    + CategoryInfo          : InvalidData: (:) [Demo-ValidateSet.ps1], Paramet
   erBindingValidationException
    + FullyQualifiedErrorId : ParameterArgumentValidationError,Demo-ValidateSe
   t.ps1

The error message displays the expected values, but the better approach might be to include them in a help message, especially if the parameter is mandatory. For example, this script will export results based on -Export.

[Parameter(Position=1,Mandatory=$True,
HelpMessage="What type of export file do you want to create? Valid choices are CSV, XML, CLIXML.")]
[ValidateSet("csv","xml","clixml")]
[string]$Export,

If you'd like to try out my demo script, you can download Demo-ValidateSet.

---

---