Parameters

Article
01/23/2017

Microsoft Exchange Server 2007 will reach end of support on April 11, 2017. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.

Applies to: Exchange Server 2007, Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

Most cmdlets rely on parameters. Parameters are elements that provide information to the cmdlet, either identifying an object and its attributes to act upon, or controlling how the cmdlet performs its task. The name of the parameter is preceded by a hyphen (-) and followed by the value of the parameter as follows:

Verb-Noun -ParameterName <ParameterValue>

In this simple example, the hyphen in front of the parameter name tells the Exchange Management Shell that the word that immediately follows the hyphen is a parameter that is passed to the cmdlet and that the next separate word after the parameter is the value of the parameter.

Positional Parameters

A positional parameter is a parameter that lets you specify the parameter's value without specifying the parameter's name. A parameter is a positional parameter if the Parameter Position attribute is an integer. This integer indicates the position on the command line where the cmdlet can find the parameter's value.

Most cmdlets only have one positional parameter, Identity. Identity is always in position 1 if it is available on a cmdlet. If a parameter is not a positional parameter, it is considered to be a named parameter. You must specify the parameter name and parameter value for named parameters.

The following two commands perform the same task: returning configuration information for a Receive connector that is named "Contoso".

Get-ReceiveConnector -Identity "Contoso"
Get-ReceiveConnector "Contoso"

Parameter Details

Included in the Parameters section of the information that is retrieved by the Get-Help cmdlet are details, also called metadata, on each parameter. The following example is from the Get-Service cmdlet.

PARAMETERS
    -ServiceName System.String[]

        Parameter required?           false
        Parameter position?           1
        Default value                 *
        Accept pipeline input?       true
        Accept wildcard characters?  True

This example from the Get-Service cmdlet includes some very specific details about the value types that can be passed for the ServiceName parameter. Not all cmdlets include such details. However, most cmdlets do include some settings for each parameter as described in Table 1.

Table 1 Parameter settings

Setting	Description
Required?	This setting indicates whether the cmdlet will run if you do not supply the parameter. When Required? is set to `True`, the Exchange Management Shell prompts you for the value if the parameter is not supplied on the command line.
Position?	This setting indicates whether you must put the parameter name in front of the parameter value. When Position? is set to `Named`, the parameter name is required. When Position? is set to an integer, the name is not required, only the value.
Default value	This setting indicates the default value for this parameter if no other value is provided.
Accept pipeline input?	This setting indicates whether the parameter can receive its value as an input through a pipeline from another cmdlet.
Accept wildcard characters?	This setting indicates whether the parameter’s value can contain wildcard characters and can be matched to multiple objects.

Boolean Parameters

Boolean parameters are used in the Exchange Management Shell to determine whether a feature or option is enabled, $True, or disabled, $False. The value that you assign to a Boolean parameter is stored in the configuration of the object that you are modifying. When you supply a value to a Boolean parameter, you must use the values $True or 1, or $False or 0. The dollar sign ($) must be included with $True and $False. You may notice that some commands insert a colon (:) between the Boolean parameter name and Boolean value. On Boolean parameters, this colon is optional. The following example disables the Receive connector "Contoso.com":

Set-ReceiveConnector "Contoso.com" -Enabled $False

Switch Parameters

Switch parameters are used in the Exchange Management Shell to set a state for the immediate execution of a command. This state is not saved between commands. Switch parameters resemble Boolean parameters but serve different purposes and require different syntax. Switch parameters do not require a value. By default, if you specify a switch parameter on a command line without a value, the parameter evaluates to $True. Switch parameters, like Boolean parameters, accept only $True or 1, or $False or 0. The dollar sign ($) must be included with $True and $False. Unlike Boolean parameters, you must include a colon (:) between the switch parameter name and switch value. The first of the following examples instructs the Exchange Management Shell to display a confirmation prompt before it lets EdgeSync synchronization start. The second example instructs the Exchange Management Shell not to display a confirmation prompt before deleting the Receive connector "Contoso.com":

Start-EdgeSynchronization -Confirm
Remove-ReceiveConnector "Contoso.com" -Confirm:$False

Common Parameters

Common parameters are parameters that are automatically added to all commands by the Exchange Management Shell. These parameters perform functions that can be used with, or used by, the commands that they are run against. Table 2 lists all the common parameters that are available in the Exchange Management Shell. Three additional parameters, WhatIf, Confirm, and ValidateOnly, may also be added to cmdlets. For more information about these additional parameters, see WhatIf, Confirm, and ValidateOnly Parameters.

Table 2 Common parameters in the Exchange Management Shell

Parameter name	Required	Type	Description
Verbose	Optional	System.Boolean	This parameter instructs the command to provide detailed information about the operation. Note Most Get cmdlets only return summary information when you run them. To tell the Get cmdlet to return verbose information when you run a command, pipe the command to the Format-List cmdlet. For more information about pipelining, see Pipelining. For more information about command output, see Working with Command Output.
Debug	Optional	System.Boolean	This parameter instructs the command to provide programmer-level detail about the operation.
ErrorAction	Optional	System.Enum	This parameter controls the behavior of the command when an error occurs. Values are as follows: `NotifyContinue`, which is the default value `NotifyStop` `SilentContinue` `SilentStop` `Inquire`, which asks the user what to do
ErrorVariable	Optional	System.String	This parameter specifies the name of the variable that the command uses to store errors that are encountered during processing. This variable is populated in addition to `$ERROR`.
OutVariable	Optional	System.String	This parameter specifies the name of the variable that the command uses for objects that are output from this command. This is equivalent to piping the command to `Set-Variable <name> -Passthru:$true`

Share via