about_Scripting_ValidateSet.help.txt
|
TOPIC
about_Scripting_ValidateSet SHORT DESCRIPTION A tutorial on verifying that a parameter value belongs to a pre-defined set of values. LONG DESCRIPTION You can use this to verify that the parameter value belongs to a pre- efined set of possible values. To use, specify a comma separated list of possible values as part of the attribute. [ValidateRange("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. 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. NOTE: 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 ) $m="Getting {0} events from {1} log on {2}" -f $count,$log,$computername Write-Verbose $m #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 C:\Scripts> .\Demo-ValidateSet.ps1 -comp jdhit-dc01 -log dns -Exp clixml C:\scripts\Demo-ValidateSet.ps1 : Cannot validate argument on parameter 'Log'. The argument "dns" does not belong to the set "System,Application, Security,Directory Service,DNS Server" specified by the ValidateSet attr ibute. Supply an argument that is in the set and then try the command ag ain. At line:1 char:45 + .\Demo-ValidateSet.ps1 -comp jdhit-dc01 -log <<<< dns -Exp clixm l + CategoryInfo : InvalidData: (:) [Demo-ValidateSet.ps1], ParameterBindingValidationException + FullyQualifiedErrorId : ParameterArgumentValidationError,Demo-Valid ateSet.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, I also recommend documenting these values in comment based help. SEE ALSO about_Functions_Advanced_Parameters http://jdhitsolutions.com/blog |