Copy Code

	Describes how to work with cmdlet parameters in Windows PowerShell. 

	Most Windows PowerShell cmdlets and functions rely on parameters to allow
	users to select options or provide input. The parameters follow the cmdlet 
	or function name and typically have the following form:

		-<parameter_name> <parameter_value>

	The name of the parameter is preceded by a hyphen (-), which signals to 
	Windows PowerShell that the word following the hyphen is a parameter and 
	not a value being passed to the cmdlet or function. Not all parameters 
	require a value, and not all parameter names must be specified. In some 
	cases, the parameter name is implied and does not need to be included in 
	the command.

	The type of parameters and the requirements for those parameters vary by 
	cmdlet and by function from cmdlet to cmdlet. To find information about the
	parameters of a cmdlet, use the Get-Help cmdlet. For example, to find 
	information about the parameters of the Get-ChildItem cmdlet, type:

		get-help get-childitem

	To find information about the parameters of a function, review the 
	parameter definitions. Parameters are defined either after the function 
	name or inside the body of the function, using the Param keyword. For more 
	information, see about_Functions.

	Some functions also contain comment-based Help about parameters. Use the 
	Get-Help cmdlet with these functions. For more information, see the help 
	topic for Get-Help and about_Comment_Based_Help. 

	The Get-Help Cmdlet returns various details about the cmdlet or function, 
	including a description of the cmdlet or function, the command syntax, 
	information about the parameters, and examples showing how to use the 
	cmdlet or function.

	You can also use the Parameter parameter of the Get-Help cmdlet or function 
	to find information about a particular parameter. Or, you can use the 
	wildcard character (*) with the Parameter parameter to find information 
	about all the parameters of the cmdlet or function. For example, the 
	following command gets information about all the parameters of the 
	Get-Member cmdlet or function:

		get-help get-member -parameter *

	This information includes the details you need to know to use the 
	parameter. For example, the Help topic for the Get-ChildItem cmdlet 
	includes the following details about its Path parameter:

		-path <string[]>
			Specifies a path of one or more locations. Wildcard characters are
			permitted. The default location is the current directory (.).

		Required?					false
		Position?					1
		Default value				Current directory
		Accept pipeline input?	 true (ByValue, ByPropertyName)
		Accept wildcard characters?  true

	The parameter information includes the parameter syntax,
	a description of the parameter, and the parameter attributes.
	The following sections describe the parameter attributes.

  Parameter Required?
	This setting indicates whether the parameter is mandatory, that
	is, whether all commands that use this cmdlet must include this
	parameter. When the value is "True" and the parameter is missing
	from the command, Windows PowerShell prompts you for a value for
	the parameter.

  Parameter Position?
	This setting indicates whether you can supply a parameter's value 
	without preceding it with the parameter name. If set to "0" or "named," 
	a parameter name is required. This type of parameter is referred to as
	a named parameter. A named parameter can be listed in any position 
	after the cmdlet name.

	If the "Parameter position?" setting is set to an integer other than 0, 
	the parameter name is not required. This type of parameter is referred 
	to as a positional parameter, and the number indicates the position 
	in which the parameter must appear in relation to other positional 
	parameters. If you include the parameter name for a positional 
	parameter, the parameter can be listed in any position after the
	cmdlet name.

	For example, the Get-ChildItem cmdlet has Path and Exclude parameters. 
	The "Parameter position?" setting for Path is 1, which means that it
	is a positional parameter. The "Parameter position?" setting for Exclude
	is 0, which means that it is a named parameter. 

	This means that Path does not require the parameter name, but its
	parameter value must be the first or only unnamed parameter value
	in the command. However, because the Exclude parameter is a named 
	parameter, you can place it in any position in the command.

	As a result of the "Parameter position?" settings for these two 
	parameters, you can use any of the following commands:

		Get-ChildItem -path c:\techdocs -exclude *.ppt
		Get-ChildItem c:\techdocs -exclude *.ppt
		Get-ChildItem -exclude *.ppt -path c:\techdocs
		Get-ChildItem -exclude *.ppt c:\techdocs

	If you were to include another positional parameter without including 
	the parameter name, that parameter would have to be placed in the order 
	specified by the "Parameter position?" setting.

  Parameter Type
	This setting specifies the Microsoft .NET Framework type of the parameter 
	value. For example, if the type is Int32, the parameter value must be an
	integer. If the type is string, the parameter value must be a 
	character string. If the string contains spaces, the value must be 
	enclosed in quotation marks, or the spaces must be preceded by the 
	escape character (`).

  Default Value
	This setting specifies the value that the parameter will assume
	if no other value is provided. For example, the default value of
	the Path parameter is often the current directory. Required
	parameters never have a default value. For many optional parameters,
	there is no default because the parameter has no effect if it is
	not used. 

  Accepts Multiple Values?
	This setting indicates whether a parameter accepts multiple
	parameter values. When a parameter accepts multiple values,
	you can type a comma-separated list as the value of the parameter
	in the command, or save a comma-separated list (an array) in a
	variable, and then specify the variable as the parameter value.

	For example, the ServiceName parameter of the Get-Service
	cmdlet accepts multiple values. The following commands are both valid:

		get-service -servicename winrm, netlogon

		$s = "winrm", "netlogon"
		get-service -servicename $s

  Accepts Pipeline Input?
	This setting indicates whether you can use the pipeline operator
	(|) to send a value to the parameter. 

	Value					Description
	-----					-----------
	False					Indicates that you cannot pipe a value to the 

	True (by Value)		Indicates that you can pipe any value to the 
							 parameter, just so the value has the .NET 
							 Framework type specified for the parameter or the
							 value can be converted to the specified .NET 
							 Framework type.

							 When a parameter is "True (by Value)", Windows 
							 PowerShell tries to associate any piped values 
							 with that parameter before it tries other methods
							 to interpret the command.

	True (by Property Name)  Indicates that you can pipe a value to the 
							 parameter, but the .NET Framework type of the 
							 parameter must include a property with the same
							 name as the parameter.
							 For example, you can pipe a value to a Name 
							 parameter only when the value has a property 
							 called "Name".

  Accepts Wildcard Characters?
	This setting indicates whether the parameter's value can contain 
	wildcard characters so that the parameter value can be matched to more 
	than one existing item in the target container.

  Common Parameters
	Common parameters are parameters that you can use with any cmdlet.
	For more information, about common parameters, type:

		help about_commonparameters