TOPIC about_Functions_Advanced_Parameters SHORT DESCRIPTION Explains how to add static and dynamic parameters to functions that declare the

CmdletBinding attribute. LONG DESCRIPTION You can declare your own parameters when you write functions, and you can write functions so that they can access the common parameters that are available to compiled cmdlets. For more information about the Windows PowerShell common parameters, see about_CommonParameters.

Static Parameters The following example shows a parameter declaration that defines a ComputerName parameter. This parameter has the following characteristics: - It is required. - It takes input from the pipeline. - It takes an array of strings as input. Param ( [parameter(Mandatory=$true, ValueFromPipeline=$true)] [String[]] $ComputerName ) The only required attribute that must be used when you declare a parameter is the Parameter attribute. However, you can also declare the Alias attribute and several validation arguments. There are no limits to the number of attributes that you can add to a parameter declaration. Parameter Attribute The Parameter attribute is used to declare a parameter of the function. This attribute has the following named arguments that are used to define the characteristics of the parameter, such as whether the parameter is required or optional. Mandatory Named Argument The Mandatory argument indicates that the parameter is required when the function is run. If this argument is not specified, the parameter is an optional parameter. The following example shows the declaration of a parameter that is required when the function is run. Param ( [parameter(Mandatory=$true)] [String[]] $ComputerName )

Position Named Argument The Position argument specifies the position of the parameter. If this argument is not specified, the parameter name or its alias must be explicitly specified when the parameter is set. Also, if none of the parameters of a function have positions, the Windows PowerShell runtime assigns positions to each parameter based on the order in which the parameters are received. The following example shows the declaration of a parameter whose value must be specified as the first argument when the cmdlet is run. Notice that this function could be run with or without specifying the name of the parameter. Param ( [parameter(Position=0)] [String[]] $ComputerName ) ParameterSetName Named Argument The ParameterSetName argument specifies the parameter set to which a parameter belongs. If no parameter set is specified, the parameter belongs to all the parameter sets defined by the function. This behavior means that each parameter set must have one unique parameter that is not a member of any other parameter set. The following example shows the parameter declaration of two parameters that belong to two different parameter sets. Param ( [parameter(Mandatory=$true, ParameterSetName=Computer)] [String[]] $ComputerName ) Param ( [parameter(Mandatory=$true, ParameterSetName=User)] [String[]] $UserName ) For more information about parameter sets, see "Cmdlet Parameter Sets" in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142183. ValueFromPipeline Named Argument The ValueFromPipeline argument specifies that the parameter accepts input from a pipeline object. Specify this argument if the cmdlet accesses the complete object, not just a property of the object. The following example shows the parameter declaration of a mandatory

ComputerName parameter that accepts the input object that is passed to the function from the pipeline. Param ( [parameter(Mandatory=$true, ValueFromPipeline=$true)] [String[]] $ComputerName ) ValueFromPipelineByPropertyName Named Argument The valueFromPipelineByPropertyName argument specifies that the parameter accepts input from a property of a pipeline object. Specify this attribute if the following conditions are true: - The parameter accesses a property of the piped object. - The property has the same name as the parameter, or the property has the same alias as the parameter. For example, if the function has a ComputerName parameter, and the piped object has a ComputerName property, the value of the ComputerName property is assigned to the ComputerName parameter of the function. The following example shows the parameter declaration of a ComputerName parameter that accepts input from the ComputerName property of the input object that is passed to the cmdlet. Param ( [parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)] [String[]] $ComputerName ) ValueFromRemainingArguments Named Argument The ValueFromRemainingArguments argument specifies that the parameter accepts all of the remaining arguments that are not bound to the parameters of the function. The following example shows the parameter declaration of a ComputerName parameter that accepts all the remaining arguments of the input object that is passed to the function. Param ( [parameter(Mandatory=$true, ValueFromRemainingArguments=$true)] [String[]] $ComputerName ) HelpMessage Named Argument The HelpMessage argument specifies a message that contains a short

description of the parameter. The following example shows a parameter declaration that provides a description of the parameter. Param ( [parameter(Mandatory=$true, HelpMessage=An array of computer names.)] [String[]] $ComputerName ) Alias Attribute The Alias attribute specifies another name for the parameter. There is no limit to the number of aliases that can be assigned to a parameter. The following example shows a mandatory parameter declaration that adds the "CN" alias to the ComputerName parameter. Param ( [parameter(Mandatory=$true)] [alias(CN)] [String[]] $ComputerName ) Parameter Validation Attributes These attributes define how the Windows PowerShell runtime validates the arguments of advanced functions. AllowNull Validation Attribute The AllowNull attribute allows the argument of a mandatory cmdlet parameter to be set to Null. In the following example, the ComputerName parameter can contain a value of Null even though this parameter is a mandatory parameter. Param ( [parameter(Mandatory=$true)] [String] [AllowNull()] $ComputerName ) AllowEmptyString Validation Attribute The AllowEmptyString attribute allows an empty string as the argument of a mandatory cmdlet parameter. In the following example, the ComputerName parameter can contain an empty string ("") even though this parameter is a mandatory parameter. Param ( [parameter(Mandatory=$true)]

[String] [AllowEmptyString()] $ComputerName ) AllowEmptyCollection Validation Attribute The AllowEmptyCollection attribute allows an empty collection as the argument of a mandatory parameter. Param ( [parameter(Mandatory=$true)] [String[]] [AllowEmptyCollection()] $ComputerName ) ValidateCount Validation Attribute The ValidateCount attribute specifies the minimum and maximum number of arguments that the parameter can accept. The Windows PowerShell runtime generates an error if the number of arguments is outside that range. In the following example, the ComputerName parameter can have one to five arguments. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateCount(1,5)] $ComputerName ) ValidateLength Validation Attribute The ValidateLength attribute specifies the minimum and maximum length of the parameter argument. The Windows PowerShell runtime generates an error if the length of the parameter argument is outside that range. In the following example, the specified computer names must have one to 10 characters. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateLength(1,10)] $ComputerName ) ValidatePattern Validation Attribute The ValidatePattern attribute specifies a regular expression that validates the pattern of the parameter argument. The Windows PowerShell runtime generates an error if the parameter argument does not match this pattern. In the following example, the argument of the parameter

must be a four-digit number, and each digit must be a number 0 to 9. Param ( [parameter(Mandatory=$true)] [String[]] [ValidatePattern("[0-9][0-9][0-9][0-9]")] $ComputerName ) ValidateRange Validation Attribute The ValidateRange attribute specifies the minimum and maximum values of the parameter argument. The Windows PowerShell runtime generates an error if the parameter argument is outside that range. In the following example, the argument of the parameter cannot be less than 0 or greater than 10. Param ( [parameter(Mandatory=$true)] [Int[]] [ValidateRange(0,10)] $Count ) ValidateScript Validation Attribute The ValidateScript attribute specifies a script that is used to validate the parameter argument. The Windows PowerShell runtime generates an error if the script result is false or if the script throws an exception. In the following example the value of the Count parameter must be less than 4. Param ( [parameter()] [Int] [ValidateScript({$_ -lt 4})] $Count ) ValidateSet Attribute The ValidateSet attribute secifies a set of valid values for the argument of the parameter. The Windows PowerShell runtime generates an error if the parameter argument does not match a value in the set. In the following example, the argument of the parameter can contain only the names Steve, Mary, and Carl. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateRange(Steve, Mary, Carl)] $UserName

) ValidateNotNull Validation Attribute The ValidateNotNull attribute specifies that the argument of the parameter cannot be set to Null. The Windows PowerShell runtime generates an error if the parameter value is Null. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateNotNull()] $UserName ) ValidateNotNullOrEmpty Validation Attribute The ValidateNotNullOrEmpty attribute specifies that the argument of the parameter cannot be set to Null or it cannot be empty. The Windows PowerShell runtime generates an error if the parameter is specified but its value is Null, an empty string, or an empty array. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateNotNullOrEmpty()] $UserName ) Dynamic Parameters Dynamic parameters are parameters of a cmdlet, function, or script that are available only under certain conditions. For example, several provider cmdlets have parameters that are available only when the cmdlet is used in the provider path. One familiar dynamic parameter is the Encoding parameter of the Set-Item, cmdlet, which is available only when the Set-Item cmdlet is used in a FileSystem provider path. To create a dynamic parameter for a function or script, use the DynamicParam keyword. The syntax is as follows. DynamicParam {<statement-list>} In the statement list, use an If statement to specify the conditions under which the parameter is available in the function. Use the New-Object cmdlet to create a System.Management.Automation.RuntimeDefinedParameter object to represent the parameter and specify its name.

You can also use a New-Object command to create a System.Management.Automation.ParameterAttribute object to represent attributes of the parameter, such as Mandatory, Position, or ValueFromPipeline or its parameter set. The following example shows a sample function with standard parameters called Name and Path, and an optional dynamic parameter named DP1. The DP1 parameter is in the PSet1 parameter set and has a type of Int32. The DP1 parameter is available in the Sample function only when the value of the Path parameter contains "HKLM:", indicating that it is being used in the HKEY_LOCAL_MACHINE registry drive. function Sample { Param ([String]$Name, [String]$Path) DynamicParam { if ($path -match "*HKLM*:") { $dynParam1 = new-object System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection) $attributes = new-object System.Management.Automation.ParameterAttribu te $attributes.ParameterSetName = 'pset1' $attributes.Mandatory = $false $attributeCollection = new-object -Type System.Collections.ObjectModel.Collection``1[System.Attribute] $attributeCollection.Add($attributes) $paramDictionary = new-object System.Management.Automation.RuntimeDefinedParameterDictionary $paramDictionary.Add("dp1", $dynParam1) return $paramDictionary } End if } } For more information, see "RuntimeDefinedParameter Class" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkID=145130.

SEE ALSO about_Advanced Functions about_Functions_Advanced_Methods about_Functions_CmdletBindingAttribute