about_Functions_Advanced_Parameters

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