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