Export (0) Print
Expand All
3 out of 4 rated this helpful - Rate this topic

Parameters

 

Applies to: Exchange Server 2013

Topic Last Modified: 2014-03-04

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.

This topic discusses the following parameters and their behavior in the Shell:

Positional parameters

Boolean parameters

Switch parameters

Common Windows PowerShell 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. For more information about the various attributes that make up a parameter, see the Parameter Details section later in this topic.

Most cmdlets only have one positional parameter, Identity. Identity is always in position 1 if it is available on a cmdlet. Some cmdlets have multiple positional parameters. With these cmdlets, you can specify the values for each positional parameter in the order specified by the Parameter Position attribute on each parameter. The values for each parameter must be in the correct position on the command line to work correctly.

If a parameter isn't a positional parameter, it's 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 of returning configuration information for a Receive connector that is named "Contoso".

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

The following two commands perform the same task. The positional parameter values in the first command are placed in the exact order as required by the Parameter Position attribute on each parameter.

Set-ExampleCmdlet "Seattle Users" $True "Contoso.com"
Set-ExampleCmdlet -Name "Seattle Users" -Enabled $True -Domain "Contoso.com"

Attributes, also called metadata, on each parameter are included in the PARAMETERS section of the Shell Help that is retrieved by the Get-Help cmdlet. 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 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 the following table.

Parameter settings

Setting Description

Required?

Indicates whether the cmdlet will run if you don't supply the parameter. When Required? is set to True, the Shell prompts you for the value if the parameter isn't supplied on the command line.

Position?

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 isn't required, only the value.

Default value

Indicates the default value for this parameter if no other value is provided.

Accept pipeline input?

Indicates whether the parameter can receive its value as an input through a pipeline from another cmdlet.

Accept wildcard characters?

Indicates whether the parameter’s value can contain wildcard characters and can be matched to multiple objects.

Boolean parameters are used in the Shell to determine, among other things, 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're 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 are commonly used to indicate whether the current command should proceed with additional prompting or to enable an alternate option for the command being run. This state isn't saved between commands. Switch parameters resemble Boolean parameters, but they serve different purposes and require different syntax. Switch parameters don't require a value. When you specify a switch parameter on a command line without a value, the parameter evaluates to $True.

On some cmdlets, the cmdlet may run as though the switch parameter was included on the command line, even if you didn't include it yourself. This behavior commonly occurs with the Confirm switch parameter on cmdlets that can cause data loss if they're inadvertently run. In the case of the Confirm switch parameter on such a cmdlet, the cmdlet will always prompt for confirmation before running unless you explicitly tell the cmdlet not to by overriding the switch parameter. You can override the switch parameter by including the Confirm switch parameter on the command line with a value of :$False. Unlike any other parameters, the colon character (:) is required between switch parameters and the value $False.

The first of the following examples instructs the Start-EdgeSynchronization cmdlet to display a confirmation prompt before it lets EdgeSync synchronization start. The second example instructs the Remove-ReceiveConnector cmdlet not to display a confirmation prompt before deleting the Receive connector "Contoso.com":

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

There are several Windows PowerShell parameters that are automatically added to all commands by the Shell. These parameters perform functions that can be used with, or used by, the commands that they're run against. The following table lists all the common parameters that are available in the 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 switches.

Common Windows PowerShell parameters in the Exchange Management Shell

Parameter name Required Type Description

Debug

Optional

System.Boolean

The Debug parameter instructs the command to provide programmer-level detail about the operation.

ErrorAction

Optional

System.Enum

The ErrorAction parameter controls the behavior of the command when an error occurs. Values are as follows:

  • Continue, which is the default value

  • Stop

  • SilentlyContinue

  • Inquire, which asks the user what to do

ErrorVariable

Optional

System.String

The ErrorVariable 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

The OutVariable 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

Verbose

Optional

System.Boolean

The Verbose parameter instructs the command to provide detailed information about the operation.

NoteNote:
Most Get cmdlets only return summary information that contains the most commonly used properties when you run them. To tell the Get cmdlet to return all of the properties on an object, pipe the command to the Format-List cmdlet.
For more information, see Pipelining and Working with Command Output.
 
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.