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 ( ...
magdula294