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.ParameterAttribute
$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