about_Functions_Advanced_Parameters
Applies To: Windows PowerShell 2.0
TOPIC
about_Functions_Advanced_Parameters
SHORT DESCRIPTION
Explains how to add parameters to advanced functions.
LONG DESCRIPTION
You can add parameters to the advanced functions that you write, and use
parameter attributes and arguments to limit the parameter values that
function users submit with the parameter.
The parameters that you add to your function are available to users in
addition to the common parameters that Windows PowerShell adds automatically
to all cmdlets and advanced functions. "For more information about the Windows
PowerShell common parameters, see about_CommonParameters.
Static Parameters
Static parameters are parameters that are always available in the function.
Most parameters in Windows PowerShell cmdlets and scripts are static parameters.
The following example shows the declaration of a ComputerName parameter that
has the following characteristics:
- It is mandatory (required).
- It takes input from the pipeline.
- It takes an array of strings as input.
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
Attributes of Parameters
This section describes the attributes that you can add to function
parameters.
All attributes are optional. However, if you omit the CmdletBinding
attribute, then to be recognized as an advanced function, the function
must include the Parameter attribute.
You can add one or multiple attributes in each parameter declaration. There
is no limit to the number of attributes that you can add to a parameter
declaration.
The Parameter Attribute
The Parameter attribute is used to declare the attributes of function
parameters.
The Parameter attribute is optional, and you can omit it if none of the
parameters of your functions need attributes, but to be recognized as
an advanced function (rather than a simple function), a function must have
either the CmdletBinding attribute or the Parameter attribute, or both.
The Parameter attribute has arguments that define the characteristics
of the parameter, such as whether the parameter is mandatory or optional.
Use the following syntax to declare the Parameter attribute, an argument,
and an argument value. The parentheses that enclose the argument and its
value must follow "Parameter" with no intervening space.
Param
(
[parameter(Argument=value)]
$ParameterName
)
Use commas to separate arguments within the parentheses. Use the
following syntax to declare two arguments of the Parameter attribute.
Param
(
[parameter(Argument1=value1,
Argument2=value2)]
)
If you use the Parameter attribute without arguments (as an alternative
to using the CmdletBinding attribute), the parentheses that follow the
attribute name are still required.
Param
(
[parameter()]
$ParameterName
)
Mandatory Argument
The Mandatory argument indicates that the parameter is required. If this
argument is not specified, the parameter is an optional parameter.
The following example declares the ComputerName parameter. It uses the
Mandatory argument to make the parameter mandatory.
Param
(
[parameter(Mandatory=$true)]
[String[]]
$ComputerName
)
Position Argument
The Position argument determines whether the parameter name is required
when the parameter is used in a command. When a parameter declaration
includes the Position argument, the parameter name can be omitted and
Windows PowerShell identifies the unnamed parameter value by its position
(or order) in the list of unnamed parameter values in the command.
If the Position argument is not specified, the parameter name (or a parameter
name alias or abbreviation) must precede the parameter value whenever the
parameter is used in a command.
The value of the Position argument is specified as an integer. A position
value of 0 represents the first position in the command, a position
value of 1 represents the second position in the command, and so on.
If a function has no positional parameters, Windows PowerShell assigns
positions to each parameter based on the order in which the parameters
are declared. However, as a best practice, do not rely on this assignment.
When you want parameters to be positional, use the Position argument.
The following example declares the ComputerName parameter. It uses the
Position argument with a value of 0. As a result, when "-ComputerName"
is omitted from command, its value must be the first or only unnamed
parameter value in the command.
Param
(
[parameter(Position=0)]
[String[]]
$ComputerName
)
NOTE: When the Get-Help cmdlet displays the corresponding "Position?" parameter
attribute, the position value is incremented by 1. For example, a parameter
with a Position argument value of 0 has a parameter attribute of
"Position? 1."
ParameterSetName 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. Therefore, to
be unique, each parameter set must have at least one parameter that is
not a member of any other parameter set.
The following example declares a ComputerName parameter in the Computer
parameter set and a UserName parameter in the User parameter set.
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Computer")]
[String[]]
$ComputerName,
[parameter(Mandatory=$true,
ParameterSetName="User")]
[String[]]
$UserName
)
For more information about parameter sets, see "Cmdlet Parameter Sets"
in the MSDN library at https://go.microsoft.com/fwlink/?LinkId=142183.
ValueFromPipeline Argument
The ValueFromPipeline argument indicates that the parameter accepts
input from a pipeline object. Specify this argument if the function
accepts the entire object, not just a property of the object.
The following example declares a ComputerName parameter that is
mandatory and accepts an object that is passed to the function
from the pipeline.
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
ValueFromPipelineByPropertyName Argument
The valueFromPipelineByPropertyName argument indicates that the
parameter accepts input from a property of a pipeline object. The
object property must have the same name or 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 declares a ComputerName parameter that is
mandatory and accepts input from the ComputerName property of the
object that is passed to the function through the pipeline.
Param
(
[parameter(Mandatory=$true,
ValueFromPipelineByPropertyName=$true)]
[String[]]
$ComputerName
)
ValueFromRemainingArguments Argument
The ValueFromRemainingArguments argument indicates that the parameter
accepts all of the parameters values in the command that are not
assigned to other parameters of the function.
The following example declares a ComputerName parameter that is
mandatory and accepts all the remaining parameter values that were
submitted to the function.
Param
(
[parameter(Mandatory=$true,
ValueFromRemainingArguments=$true)]
[String[]]
$ComputerName
)
HelpMessage Argument
The HelpMessage argument specifies a string that contains a brief
description of the parameter or its value. Windows PowerShell displays
this message in the prompt that appears when a mandatory parameter value
is missing from a command. This argument has no effect on optional parameters.
The following example declares a mandatory ComputerName parameter and a
help message that explains the expected parameter value.
Param
(
[parameter(mandatory=$true,
HelpMessage="Enter one or more computer names separated by commas.")]
[String[]]
$ComputerName
)
Alias Attribute
The Alias attribute establishes an alternate name for the parameter. There
is no limit to the number of aliases that you can assign to a parameter.
The following example shows a parameter declaration that adds the "CN" and
"MachineName" aliases to the mandatory ComputerName parameter.
Param
(
[parameter(Mandatory=$true)]
[alias("CN","MachineName")]
[String[]]
$ComputerName
)
Parameter Validation Attributes
Parameter validation attributes direct Windows PowerShell to test the parameter
values that users submit when they call the advanced function. If the parameter
values fail the test, an error is generated and the function is not called.
AllowNull Validation Attribute
The AllowNull attribute allows the value of a mandatory parameter
to be null ($null). The following example declares a ComputerName parameter
that can have a Null value.
Param
(
[parameter(Mandatory=$true)]
[AllowNull()]
[String]
$ComputerName
)
AllowEmptyString Validation Attribute
The AllowEmptyString attribute allows the value of a mandatory parameter to be
an empty string (""). The following example declares a ComputerName parameter
that can have an empty string value.
Param
(
[parameter(Mandatory=$true)]
[AllowEmptyString()]
[String]
$ComputerName
)
AllowEmptyCollection Validation Attribute
The AllowEmptyCollection attribute allows the value of a mandatory parameter
to be an empty collection (@()). The following example declares a ComputerName
parameter that can have a empty collection value.
Param
(
[parameter(Mandatory=$true)]
[AllowEmptyCollection()]
[String[]]
$ComputerName
)
ValidateCount Validation Attribute
The ValidateCount attribute specifies the minimum and maximum number
of parameter values that the parameter accepts. Windows PowerShell
generates an error if the number of parameter values in the command that
calls the function is outside that range.
The following parameter declaration creates a ComputerName parameter that
takes 1 to 5 parameter values.
Param
(
[parameter(Mandatory=$true)]
[ValidateCount(1,5)]
[String[]]
$ComputerName
)
ValidateLength Validation Attribute
The ValidateLength attribute specifies the minimum and maximum number
of characters in each parameter value. Windows PowerShell generates an
error if the length of any value of the parameter is outside of the range.
In the following example, each computer name must have one to 10
characters.
Param
(
[parameter(Mandatory=$true)]
[ValidateLength(1,10)]
[String[]]
$ComputerName
)
ValidatePattern Validation Attribute
The ValidatePattern attribute specifies a regular expression that
is compared to the parameter value. Windows PowerShell generates
an error if the parameter value does not match the regular expression
pattern.
In the following example, the parameter value must be a four-digit
number, and each digit must be a number 0 to 9.
Param
(
[parameter(Mandatory=$true)]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
[String[]]
$ComputerName
)
ValidateRange Validation Attribute
The ValidateRange attribute specifies a numeric range for each
parameter value. Windows PowerShell generates an error if any
parameter value is outside that range. In the following example,
the value of the Attempts parameter must be between 0 and 10.
Param
(
[parameter(Mandatory=$true)]
[ValidateRange(0,10)]
[Int]
$Attempts
)
ValidateScript Validation Attribute
The ValidateScript attribute specifies a script that is used
to validate the parameter value. Windows PowerShell pipes the
parameter value to the script and generates an error if the
script returns "false" or if the script throws an exception.
When you use the ValidateScript attribute, the parameter value
that is being validated is mapped to the $_ variable. You can
use the $_ variable to refer to the parameter value in the script.
In the following example, the value of the EventDate parameter
must be greater than or equal to the current date.
Param
(
[parameter()]
[ValidateScript({$_ -ge (get-date)})]
[DateTime]
$EventDate
)
ValidateSet Attribute
The ValidateSet attribute specifies a set of valid values for the
parameter. Windows PowerShell generates an error if the parameter
does not match a value in the set. In the following example, the
value of the Detail parameter can only be "Low," "Average," or
"High."
Param
(
[parameter(Mandatory=$true)]
[ValidateSet("Low", "Average", "High")]
[String[]]
$Detail
)
ValidateNotNull Validation Attribute
The ValidateNotNull attribute specifies that the parameter
value cannot be null ($null). Windows PowerShell generates an
error if the parameter value is null.
The ValidateNotNull attribute is designed to be used when the
type of the parameter value is not specified or when the specified
type will accept a value of Null. (If you specify a type that will
not accept a null value, such as a string, the null value will be
rejected without the ValidateNotNull attribute, because it does not
match the specified type.)
In the following example, the value of the ID parameter
cannot be null.
Param
(
[parameter(Mandatory=$true)]
[ValidateNotNull()]
$ID
)
ValidateNotNullOrEmpty Validation Attribute
The ValidateNotNullOrEmpty attribute specifies that the parameter
value cannot be null ($null) and cannot be an empty string ("").
Windows PowerShell generates an error if the parameter is used in
a function call, but its value is null, an empty string, or an empty
array.
Param
(
[parameter(Mandatory=$true)]
[ValidateNotNullOrEmpty()]
[String[]]
$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 drive, or in
a particular path of the provider drive. For example, the Encoding
parameter is available on the Add-Content, Get-Content, and Set-Content
cmdlets only when it is used in a file system drive.
You can also create a parameter that appears only when another parameter
is used in the function command or when another parameter has a certain
value.
Dynamic parameters can be very useful, but use them only when necessary,
because they can be difficult for users to discover. To find a dynamic
parameter, the user must be in the provider path, use the ArgumentList
parameter of the Get-Command cmdlet, or use the Path parameter of Get-Help.
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 named 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 Get-Sample {
[CmdletBinding()]
Param ([String]$Name, [String]$Path)
DynamicParam
{
if ($path -match ".*HKLM.*:")
{
$attributes = new-object System.Management.Automation.ParameterAttribute
$attributes.ParameterSetName = "__AllParameterSets"
$attributes.Mandatory = $false
$attributeCollection = new-object `
-Type System.Collections.ObjectModel.Collection[System.Attribute]
$attributeCollection.Add($attributes)
$dynParam1 = new-object `
-Type System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection)
$paramDictionary = new-object `
-Type System.Management.Automation.RuntimeDefinedParameterDictionary
$paramDictionary.Add("dp1", $dynParam1)
return $paramDictionary
}
}
}
For more information, see "RuntimeDefinedParameter Class" in
the MSDN (Microsoft Developer Network) library at
https://go.microsoft.com/fwlink/?LinkID=145130.
SEE ALSO
about_Functions
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_CmdletBindingAttribute