about_Scripting_ValidateScript.help.txt

TOPIC
    about_Scripting_ValidateScript
 
SHORT DESCRIPTION
    A tutorial on validating a parameter value with a short scriptblock.
     
LONG DESCRIPTION
    Sometimes validating a parameter value can get a little complex. However,
    we can use PowerShell to assist in the validation effort by running the
    parameter value through a short script. Well, technically a scriptblock.
     
    To use this attribute we’ll insert a scriptblock inside the parentheses.
    The scriptblock can be as complicated as you need it to be, but it must
    evaluate to either True or False. Use $_ to indicate the parameter value.
     
    So using my datetime example, I might use a validation script like this:
 
    Param (
    [Parameter(Position=0,Mandatory=$True,
    HelpMessage="Enter a date",ValueFromPipeline=$True)]
    [ValidateScript( {
     [datetime]$start="1/1/2012"
     $end=Get-Date
     ($_ -ge $start) -AND ($_ -le $end)
     }
     )]
    [datetime]$Date
    )
 
    Process {
    write-host $date -ForegroundColor Green
    }
     
    With a validation script I have much more flexibility. Now look at the
    results:
 
    PS C:\Scripts> "2/12/2012","5/1/2012","3/15/2012","12/1/2011",
    >> "13/2/2012" | .\Demo-ValidateScript-Date.ps1 | clip
    >>
     
    2/12/2012 12:00:00 AM
    C:\scripts\Demo-ValidateScript-Date.ps1 : Cannot validate argument on
    parameter 'Date'. The "[datetime]$start="1/1/2012"
     $end=Get-Date
     ($_ -ge $start) -AND ($_ -le $end)
     " validation script for the argument with value "5/1/2012 12:00:00 AM"
     did not return true. Determine why the validation script failed and
     then try the command again.
    At line:1 char:92
    + "2/12/2012","5/1/2012","3/15/2012","12/1/2011","13/2/2012" | .
    \Demo-ValidateScript-Date.ps1 <<<< | clip
        + CategoryInfo : InvalidData: (5/1/2012:String) [Demo-
        ValidateScript-Date.ps1], ParameterBindingValidationException
        + FullyQualifiedErrorId : ParameterArgumentValidationError,Demo-
        ValidateScript-Date.ps1
 
    ...
     
    C:\scripts\Demo-ValidateScript-Date.ps1 : The input object cannot be
    bound to any parameters for the command either because the command does
    not take pipeline input or the input and its properties do not match
    any of the parameters that take pipeline input.
    At line:1 char:92
    + "2/12/2012","5/1/2012","3/15/2012","12/1/2011","13/2/2012" | .\Demo-
    ValidateScript-Date.ps1 <<<<
        + CategoryInfo : InvalidArgument: (13/2/2012:String) [Demo-
        ValidateScript-Date.ps1], ParameterBindingException
        + FullyQualifiedErrorId : InputObjectNotBound,Demo-ValidateScript-
        ate.ps1
         
    The valid dates pass, dates outside the range fail the validation test
    and the last value which isn’t a legal date also fails but with a slightly
    different error message.
     
    As with all of the validation attributes I could have inserted this code
    into the body of my script and thrown my own errors. That choice is up to
    you.
     
    [ValidateScript()] isn’t difficult to use. Just remember to insert your
    commands into a scriptblock, use $_ for the parameter value, and make sure
    the scriptblock results in either $True or $False.
 
SEE ALSO
    about_Functions_Advanced_Parameters
    http://jdhitsolutions.com/blog