Export (0) Print
Expand All
Expand Minimize

White Paper: Exchange Management Shell

 

Topic Last Modified: 2010-01-27

David Strome, Technical Writer, Microsoft Exchange Server

February 2007

This white paper introduces the Exchange Management Shell to individuals who administer Microsoft Exchange Server 2007.

The Exchange Management Shell, built on Microsoft Windows PowerShell technology, provides administrators a powerful command-line interface that they can use to administer Exchange 2007. With the Exchange Management Shell, administrators can manage every aspect of Exchange 2007. They can enable new e-mail accounts and configure Simple Mail Transfer Protocol (SMTP) connectors, store database properties, transport agents, and more. The Exchange Management Shell can perform every task that can be performed by Exchange Management Console in addition to tasks that can't be performed in the Exchange Management Console. In fact, when a task is performed in the Exchange Management Console, the same command is made available to the Exchange Management Shell and is called to process the request. For more information about the new Exchange Management Console, see New Administration Functionality in the Exchange Management Shell.

Objectives and acknowledgements   Much of the information in this white paper originally appeared as individual Help topics in the Exchange Server 2007 Help. In this white paper, we have consolidated the information you need to use the Exchange Management Shell to administer Exchange 2007. It covers numerous fundamental concepts, such as pipelining, the Identity parameter, and cmdlets, in addition to arrays, the WhatIf and Confirm parameters, script security, and operators.

noteNote:
To print this white paper, click Printer Friendly Version in your Web browser.

The Exchange Management Shell is a snap-in that relies on Windows PowerShell. Therefore, Windows PowerShell must be installed on the computer that will be running the Exchange Management Shell. To install Windows PowerShell, you must install the Microsoft .NET 2.0 Framework on the computer that will run Windows PowerShell. For information about how to download the .NET Framework, see the Microsoft .NET Framework Developer Center.

Return to top

The Exchange Management Shell provides a robust and flexible scripting platform that can reduce the complexity of current Microsoft Visual Basic scripts. What previously took hundreds of lines in Visual Basic scripts can now be done by using as little as one line of code in the Exchange Management Shell.

The Exchange Management Shell provides this flexibility because it doesn't use text as the basis for interaction with the system. It uses an object model that is based on the Microsoft .NET platform. This object model enables the shell commands to apply the output from one command to subsequent commands when they are run.

Figure 1 illustrates the design and layout of the Exchange Management Shell.

Figure 1   The Exchange Management Shell

Exchange Management Shell showing mailbox move

The following are key features of the Exchange Management Shell:

  • Command-line interface   The command-line interface lets you quickly and easily access and modify Exchange 2007 features and their values. It also gives you the flexibility to easily perform tasks in bulk that would have taken many lines of code or hours of work to apply changes through Exchange System Manager.

  • Piping of data between commands   Pipelining makes you even more productive when you administer Exchange 2007 through the Exchange Management Shell. Pipelining helps you use output from one command as input in other commands. This lets you easily perform bulk operations based on criteria applied to filtering commands that then supply the objects to be modified to commands down the "pipe". This feature is a primary reason why the Exchange Management Shell makes it possible to reduce dozens of lines of code to a single chain of commands.

  • Structured data support   Because all output from all the commands in the Exchange Management Shell is an object, all output from the commands can be acted on and processed by other commands by using little or no manipulation. Commands in a particular feature set accept output from other commands in that same feature set, without manipulation.

  • Extensive support for scripting   When you want to perform complex processes, automate functions for Help Desk account management, monitor performance, or enable other automated administrative tasks, the Exchange Management Shell provides a powerful object model environment based on the .NET platform.

  • Safe Scripting   To enable a smooth transition from a test environment to production or just to verify that your commands work correctly before you apply them to actual data, the Exchange Management Shell lets you test your commands to make sure they do what you want. You can verify the changes to be made, confirm that you want to continue, and verify that the process will succeed from end to end.

  • Access Cmd.exe commands   The Exchange Management Shell provides transparent access to the commands that are available through the command prompt (Cmd.exe). You can even take the output of Cmd.exe commands and perform actions based on that output, or integrate that output into the data that you provide to another command.

  • Trusted scripts   To improve security, the Exchange Management Shell requires that all scripts are digitally signed before they are allowed to run. This requirement prevents malicious parties from inserting a harmful script in the Exchange Management Shell. Only scripts that you specifically trust are allowed to run. This precaution helps protect you and your organization.

  • Profile customization   While the default installation of the Exchange Management Shell gives you a fully featured and easy-to-use interface, you may want to add shortcuts to the commands that you frequently use. You might also want to adjust the interface to suit your tasks. You can edit your personal Exchange Management Shell profile. This lets you control how your interface is configured and what commands automatically run when the Exchange Management Shell starts. Profile customization lets you assign scripts to aliases that you frequently use in the daily administration of your Exchange 2007 organization.

  • Extensible shell support   If you don't like the way that data is displayed or if, for example, you can't remember which collections use the Count property and which collections use the Length property, you can easily make adjustments. The Exchange Management Shell uses XML to let you modify many aspects of its behavior. Developers can create new commands to integrate with the built-in Exchange Management Shell commands. This extensibility gives you more control over your Exchange 2007 organization and helps you streamline business processes.

Return to top

The Exchange Management Shell, built on Windows PowerShell technology formerly codenamed "Monad", provides a powerful command-line interface and associated command-line plug-ins for Exchange Server that enable automation of administrative tasks. With the Exchange Management Shell, administrators can manage every aspect of Exchange 2007. They can enable new e-mail accounts and configure SMTP connectors, store database properties, transport agents, and more. The Exchange Management Shell can perform every task that can be performed by Exchange Management Console in addition to tasks that cannot be performed in Exchange Management Console. In fact, when a task is performed in the Exchange Management Console, the same command is made available to the Exchange Management Shell and called to process the request.

The Exchange Management Shell also provides a robust and flexible scripting platform that can reduce the complexity of current Microsoft Visual Basic scripts. Tasks that previously required many lines in Visual Basic scripts can now be done by using as little as one line of code in the Exchange Management Shell.

The Exchange Management Shell provides this flexibility because it does not use text as the basis for interaction with the system, but uses an object model that is based on the Microsoft .NET platform. This object model enables the Exchange Management Shell cmdlets to apply the output from one command to subsequent commands when they are run.

You can open the Exchange Management Shell by using either of the following procedures. Each procedure loads the Exchange Management Shell snap-in into the Windows PowerShell. If you don't load the Exchange Management Shell snap-in before you run an Exchange Management Shell cmdlet, you will receive an error.

To open the Exchange Management Shell from the Programs menu
  1. Click Start, click Programs, and then click Microsoft Exchange Server 2007.

  2. Click Exchange Management Shell.

To add the Exchange Management Shell snap-in from Windows PowerShell
  1. Click Start, click Programs, and then click Windows PowerShell 1.0.

  2. Click Windows PowerShell.

  3. Type the following command:

    Add-PSSnapin Microsoft.Exchange.Management.PowerShell.Admin
    

Return to top

In Exchange 2007, the Exchange Management Shell provides many help resources to help you use it to its fullest potential. This topic describes the following help resources and functionality:

  • Exchange 2007 Help file   The Exchange 2007 Help file contains all the cmdlet help topics in a role-based and task-based hierarchy. The cmdlet help topics also link to procedural topics that tell you how to perform specific tasks.

  • Help cmdlets   The Exchange Management Shell has several help cmdlets that enable you to find the appropriate information to accomplish your task.

  • Help views   Help in the Exchange Management Shell contains extensive information about the cmdlets that are available to you. Help views enable you to access the information that you need about a cmdlet.

  • Cmdlet roles, components, and functionality   Cmdlets can be listed by their role, component, or the functionality they manage. This lets you to find the appropriate cmdlet for the role, component, or functionality that you want to manage.

  • Tab completion   You can use tab completion on cmdlet names and parameter names to reduce the amount of typing you must do on the command line.

The Exchange 2007 Help file contains the same cmdlet help information that is available on each cmdlet in the Exchange Management Shell. However, in the Exchange 2007 Help file, the help for all the cmdlets is organized by server role and administration task to help you easily find specific cmdlets that are associated with the task that you want to perform. Also, cmdlet topics in the Exchange 2007 Help file are linked to topics that introduce you to the features that they manage, show you how to use the cmdlets to manage that feature, and provide specific details about the feature or common scenarios.

For more information about the cmdlet help topics available in the Exchange 2007 Help file, see Exchange Management Shell.

The following tables provide examples of how to use the Get-Help, Get-Command, and Get-ExCommand cmdlets to access the help information that is available for each cmdlet in the Exchange Management Shell.

Table 1 provides examples of how the Get-Help cmdlet is used.

Table 1   Examples of how to use the Get-Help command

Command Description

Get-Help

When you use the Get-Help cmdlet by itself, it gives you basic instructions on how to use the Exchange Management Shell help system.

Get-Help <cmdlet>

When you give the Get-Help cmdlet a shell cmdlet as an argument, it displays the help information for that cmdlet. For example, to retrieve the help information for the Get-SystemMessage cmdlet, use the following command:

Get-Help Get-SystemMessage

Get-Help <*cmdlet*>

When you give the Get-Help cmdlet a shell cmdlet as an argument, together with a wildcard character, the Get-Help cmdlet returns a list of all cmdlets that match the text that you provided. You can use several methods to retrieve a list of shell cmdlets. These methods include the following:

  • Get-Help *Rules   This command returns all cmdlets that end with the word Rules.

  • Get-Help Get*Rules   This command returns all cmdlets that start with the word Get and end with the word Rules.

  • Get-Help Get-Export*   This command returns all cmdlets that start with the phrase Get-Export.

By using wildcard characters in this manner, you can easily view a list of all cmdlets that are available for a certain feature. For example, by using the Get-Help *-TransportAgent command, you can view a list of all the cmdlet verbs available for transport agents.

Get-Help About_*

The Get-Help About_* command provides a list of all general Exchange Management Shell help topics to help you better understand and use the Exchange Management Shell. If you want to learn more about a topic in the list that is displayed, run the Get-Help About_<feature> command. For example, if you want to learn more about the Where statement, run Get-Help About_Where.

Get-Help <cmdlet> -Detailed

See the "Help Views" section later in this white paper.

Get-Help <cmdlet> -Full

See the "Help Views" section later in this white paper.

Get-Help <cmdlet> -Examples

See the "Help Views" section later in this white paper.

Get-Help <cmdlet> -Parameter <parameter name>

See the "Help Views" section later in this white paper.

Get-Help -Role *<server role>*

See the "Role, Component, and Functionality Parameters" section later in this white paper.

Get-Help -Component *<component feature>*

See the "Role, Component, and Functionality Parameters" section later in this white paper.

Get-Help -Functionality *<Global | User | Server>*

See the "Role, Component, and Functionality Parameters" section later in this white paper.

Table 2 provides examples of how the Get-Command cmdlet is used.

Table 2   Examples of how to use the Get-Command command

Cmdlet Description

Get-Command

The Get-Command cmdlet provides a list of all the cmdlets that are available to the shell. Like the Get-Help cmdlet, the Get-Command cmdlet allows for wildcard character expansion. You can use this cmdlet with the Format-List and Format-Table cmdlets to provide a more readable display. For example, use Get-Command | Format-List to display the cmdlet help in a list format.

Get-Command <Cmdlet>

The Get-Command <Cmdlet> command provides detailed information about the parameters of the specified cmdlet and other components. You can use this command together with the Format-List cmdlet and Format-Table cmdlet to provide a more readable display. For example, use Get-Command Get-SystemMessage | Format-List to display the cmdlet help in a list format.

Get-Command -Noun <CmdletNoun>

The Get-Command -Noun <CmdletNoun> command lists all the cmdlets that exist with the specified noun. This command is useful when you want to view a list of all cmdlets that are associated with a particular feature. For example, the Get-Help -Noun SystemMessage command returns all the cmdlets that are available for the SystemMessage feature. You can use this command together with the Format-List cmdlet and Format-Table cmdlet to provide a more readable display. For example, use Get-SystemMessage -Noun Get | Format-List to display the command help in a list format.

Get-Command -Verb <CmdletVerb>

The Get-Command -Verb <CmdletVerb> command lists all the cmdlets that exist with the specified verb. This command is useful when you want to view a list of all cmdlets that are associated with a particular action. For example, the Get-Help -Verb Enable command returns all cmdlets available that perform the enable action. You can use this command together with the Format-List cmdlet and Format-Table cmdlet to provide a more readable display. For example, use Get-Command -Verb SystemMessage | Format-List to display the command help in a list format.

Get-ExCommand

The Get-ExCommand cmdlet behaves identically to the Get-Command cmdlet, but returns only cmdlets that are available to manage Exchange 2007.

Get-PSCommand

The Get-PSCommand cmdlet behaves identically to the Get-Command cmdlet, but excludes cmdlets that are used to manage Exchange 2007.

Table 3 provides examples of how to use miscellaneous help commands.

Table 3   Examples of how to use miscellaneous help commands

Cmdlet Description

QuickRef

The QuickRef command opens a printable HTML chart that lists the most frequently used Exchange Management Shell cmdlets.

To view the most up-to-date version of this chart, see Exchange Management Shell Quick Reference.

<Cmdlet> -?

Use the <Cmdlet> -? command together with any cmdlet to find the same help information that is available when you use the Get-Help cmdlet. For example, type Get-SystemMessage -? to display detailed help for the Get-SystemMessage cmdlet.

Get-Tip

The Get-Tip cmdlet generates a new Exchange Management Shell Tip of the Day.

Get-ExBlog

The Get-ExBlog cmdlet opens Microsoft Internet Explorer to display the Exchange Team blog.

When a cmdlet is specified as a parameter of the Get-Help cmdlet, the help information for the specified cmdlet is displayed. In some cases, the information that is returned can be extensive, and you may only want to see specific information. Help views enable you to view specific information about a cmdlet without having to sort through information that you may not need.

The Exchange Management Shell gives you four views that present exactly the information that you want. You can also retrieve a specific parameter or set of similar parameters. Table 4 shows the sections that are displayed in each view.

Table 4   Exchange Management Shell help views

Help view Default Detailed Full Examples

Synopsis

X

X

X

X

Syntax

X

X

X

 

Detailed description

X

X

X

 

Parameters without metadata

 

X

 

 

Parameters with metadata

 

 

X

 

Input type

 

 

X

 

Return type

 

 

X

 

Errors

 

 

X

 

Notes

 

 

X

 

Examples

 

X

X

X

Related links

X

 

X

 

Remarks

X

X

 

 

Table 5 describes each view and provides an example of a command that calls each view.

Table 5   Examples of Exchange Management Shell help views

Help view Example Description

Default

Get-Help Set-Mailbox

The default view is displayed when you use the command Get-Help <cmdlet>.

Detailed

Get-Help Set-Mailbox -Detailed

The Detailed view is displayed when you use the command Get-Help <cmdlet> -Detailed. The parameters that are returned in the Parameters section do not include parameter metadata.

For more information about parameters, see "Parameters" later in this white paper.

Full

Get-Help Set-Mailbox - Full

The Full view is displayed when you use the command Get-Help <cmdlet> -Full. The parameters that are returned in the Parameters section include the following parameter metadata:

  • Required?

  • Position?

  • Default value

  • Accept pipeline input?

  • Accept wildcard characters?

For more information about parameters, see "Parameters" later in this white paper.

Examples

Get-Help Set-Mailbox -Examples

The Examples view is displayed when you use the command Get-Help <cmdlet> -Examples.

In addition to these four help views, the Exchange Management Shell also lets you access the description and metadata on a specific parameter or set of similar parameters. You can specify the parameter together with the Get-Help <cmdlet> command. The following example shows how you can display the description of the ForwardingAddress parameter on the Set-Mailbox cmdlet:

Get-Help Set-Mailbox -Parameter ForwardingAddress

You can also display a set of similar parameters that exist on a specific cmdlet if you specify the partial name of a parameter together with a wildcard character (*). The following example shows how you can display all the parameters on the Set-Mailbox cmdlet that contain the word "Quota":

Get-Help Set-Mailbox -Parameter *Quota*

When you call the Get-Help cmdlet without specifying a specific cmdlet, you receive a listing of all cmdlets available in the Exchange Management Shell. However, you may want to view a list of cmdlets that manage a specific server role or component feature or that affect objects across a certain scope of functionality. The Get-Help cmdlet lets you do this with three parameters: Role, Component, and Functionality.

When you use the Get-Help cmdlet with the Role, Component, or Functionality parameters, you must enclose the values that you specify with these parameters in wildcard characters (*). The following are examples of how to call Get-Help with each parameter:

Get-Help -Role *Mailbox*
Get-Help -Component *Recipient*
Get-Help -Functionality *Server*

The following tables list all the values that can be used with the Role, Component, and Functionality parameters on the Get-Help cmdlet. Table 6 lists the values that can be used with the Role parameter.

Table 6   Valid values for Get-Help -Role

Role Value Alternative value

Mailbox

Mailbox

MB

Hub Transport

Hub

HT

Client Access

ClientAccess

CA

Unified Messaging

UnifiedMessaging

UM

Edge Transport

Edge

ET

Organization Administrator

OrgAdmin

OA

Server Administrator

SrvAdmin

SV

Recipient Administrator

RcptAdmin

RA

Windows Administrator

WinAdmin

WA

Read Only

ReadOnly

RO

Table 7 lists the values that can be used with the Component parameter.

Table 7   Valid values for Get-Help -Component

Value Value

Addressing

Mailflow

Agent

ManagedFolder

Antispam

Mobility

AutoDiscover

OAB

Calendaring

Outlook

Certificate

OWA

Classification

Permission

Client

Pop

Cluster

PublicFolder

Compliance

Queuing

Delegate

Recipient

Diagnostic

Routing

Domain

Rule

Extensibility

Search

FreeBusy

Server

GAL

Statistics

Group

Storage

HighAvailability

UM

Imap

VirtualDirectory

Mailbox

 

Table 8 lists the values that can be used with the Functionality parameter.

Table 8   Valid values for Get-Help -Functionality

Value

Global

Server

User

Tab completion enables you to reduce the typing you must do when you use the Exchange Management Shell. When you type a partial cmdlet name, press the TAB key, and the Exchange Management Shell will complete the cmdlet name if a matching cmdlet is found. If multiple matching cmdlet names are found, each cmdlet name will cycle through as you press the TAB key. When you use tab completion with cmdlet names, you must supply at least the verb and the hyphen (-). The following examples show how you can use tab completion when you enter a cmdlet name:

Get-Transport<Tab>
Enable-<Tab>

As you press the TAB key in the first example, the Exchange Management Shell cycles through all the cmdlet names that start with Get-Transport. In the second example, the Exchange Management Shell cycles through all cmdlets with the verb Enable.

As with cmdlet names, you can also use tab completion when you want the Exchange Management shell to complete the partial parameter name that you have entered. When you use tab completion with parameter names, you must specify the full cmdlet name either by typing it in directly or by using tab completion. The following examples show how you can use tab completion when you enter a parameter name:

Set-Mailbox -Email<Tab>
New-TransportRule -Cond<Tab>

As you press the TAB key in the first example, the Exchange Management Shell cycles through all the parameter names that start with Email on the Set-Mailbox cmdlet. In the second example, when you press the TAB key, the Exchange Management Shell completes the Condition parameter on the New-TransportRule cmdlet.

Return to top

A cmdlet, pronounced "command-let", is the smallest unit of functionality in the Exchange Management Shell. Cmdlets resemble built-in commands in other shells, for example, the dir command found in cmd.exe. Like these familiar commands, cmdlets can be called directly from the command line in the Exchange Management Shell and run under the context of the shell, not as a separate process.

Cmdlets are usually designed around repetitive administrative tasks, and, in the Exchange Management Shell, more than 360 cmdlets are provided for Exchange-specific management tasks. These are available in addition to the non-Exchange system administrative cmdlets included in the basic Windows PowerShell shell design.

importantImportant:
To access Exchange Management Shell cmdlets, you must load the Exchange Management Shell from the Exchange 2007 program menu.

All cmdlets in the Exchange Management Shell are presented in verb-noun pairs. The verb-noun pair is always separated by a hyphen (-) without spaces, and the cmdlet nouns are always singular. Verbs refer to the action that the cmdlet takes. Nouns refer to the object on which the cmdlet takes action. For example, in the Get-SystemMessage cmdlet, the verb is Get, and the noun is SystemMessage. All Exchange Management Shell cmdlets that manage a particular feature share the same noun. Table 9 provides examples of some of the verbs available in the Exchange Management Shell.

noteNote:
By default, if the verb is omitted, the Exchange Management Shell assumes the Get verb. For example, when you call Mailbox, you retrieve the same results as when you call Get-Mailbox.

Table 9   Examples of verbs in the Exchange Management Shell

Verb Description

Disable

Disable cmdlets set the Enabled status of the specified Exchange 2007 object to $False. This prevents the object from processing data even though the object exists.

Enable

Enable cmdlets set the Enabled status of the specified Exchange 2007 object to $True. This enables the object to process data.

Get

Get cmdlets retrieve information about a particular Exchange 2007 object.

noteNote:
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 the Format-List command, see "Working with Command Output" later in this white paper. For more information about pipelining, see "Pipelining" later in this white paper.

Install

Install cmdlets install a new object or feature on an Exchange 2007 server.

Move

Move cmdlets relocate the specified Exchange 2007 object from one container or server to another.

New

New cmdlets create new Exchange 2007 object.

Remove

Remove cmdlets delete the specified Exchange 2007 object.

Set

Set cmdlets modify the properties of an existing Exchange 2007 object.

Test

Test cmdlets test specific Exchange 2007 components and provide log files that you can examine.

Uninstall

Uninstall cmdlets remove an object or feature from an Exchange 2007 server.

The following list of cmdlets is an example of a complete cmdlet set. This cmdlet set is used to manage the delivery status notification (DSN) message and mailbox quota message features of Exchange 2007:

  • Get-SystemMessage

  • New-SystemMessage

  • Remove-SystemMessage

  • Set-SystemMessage

Return to top

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.

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"

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 10.

Table 10   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 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 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 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 11 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 11   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.

noteNote:
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" later in this white paper. For more information about command output, see "Working with Command Output" later in this white paper.

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

Return to top

The Identity parameter is a special parameter that you can use with most cmdlets. The Identity parameter gives you access to the unique identifiers that refer to a particular object in Exchange 2007. This lets you perform actions on a specific Exchange 2007 object.

The primary unique identifier of an object is always a GUID. A GUID is a 128-bit identifier, such as 63d64005-42c5-4f8f-b310-14f6cb125bf3. This GUID never repeats and is therefore always unique. However, you don't want to type such GUIDs regularly. Therefore the Identity parameter typically also consists of the values of other parameters, or combined set of values from multiple parameters on a single object. These are also guaranteed to be unique across that set of objects. You can specify the values of these other parameters, such as Name and DistriguishedName, or they can be system-generated. The additional parameters that are used, if any, and how they are populated, depend on the object you refer to.

The Identity parameter is also considered a positional parameter. The first argument on a cmdlet is assumed to be the Identity parameter when no parameter label is specified. This reduces the number of keystrokes when you type commands.

The following example shows the use of the Identity parameter by using the Receive connector's unique Name parameter value. This example also shows how you can omit the Identity parameter name because Identity is a positional parameter.

Get-ReceiveConnector -Identity "From the Internet"
Get-ReceiveConnector "From the Internet"

Like all objects in Exchange 2007, this Receive connector can also be referred to by its unique GUID. For example, if the Receive connector named "From the Internet" is also assigned the GUID 63d64005-42c5-4f8f-b310-14f6cb125bf3, you can also retrieve the Receive connector by using the following command:

Get-ReceiveConnector 63d64005-42c5-4f8f-b310-14f6cb125bf3

The examples in this section refer to the delivery status notification (DSN) messages that can be configured in an Exchange 2007 organization. The first example shows how to retrieve DSN 5.4.1 by using the Get-SystemMessage cmdlet. In the Get-SystemMessage cmdlet, the Identity parameter consists of several pieces of data that are configured on each DSN message object. These pieces of data include the language that the DSN is written in, whether the DSN is internal or external in scope, and the DSN message code as in the following example:

Get-SystemMessage en\internal\5.4.1

You can also retrieve this DSN message by using its GUID as in the following example, because all objects in Exchange 2007 have a GUID:

Get-SystemMessage 82ca7bde-1c2d-4aa1-97e1-f298a6f10222

For more information about the makeup of the Identity parameter when it is used with the SystemMessage cmdlets, see "DSN Message Identity" in Exchange Server 2007 Help.

These examples illustrate how the Identity parameter can accept different unique values to refer to specific objects in the Exchange 2007 organization. These examples also illustrate how the Identity parameter label can be omitted to reduce the number of keystrokes when you type commands.

Return to top

This topic explains how to read the Exchange Management Shell parameter sets and examples in the Exchange Help documentation and how to format a command so that the Exchange Management Shell can process the command. In the Exchange Management Shell, parameter sets are displayed in the Usage section of a cmdlet help topic. In the Exchange Server 2007 Help file, parameter sets are displayed in the Syntax section of the cmdlet help topic.

For more information about cmdlet help, see "Getting Help" earlier in this white paper.

The Exchange Management Shell follows several command conventions that help you understand what information is required or optional when you run a command and how you must present the parameters and their values. See the "Parameter Sets" section later in this white paper for examples of how parameter sets are presented in the Exchange Management Shell Help and Exchange 2007 Help file.

Table 12 lists these command conventions.

Table 12   Exchange Management Shell command conventions

Symbol Description

-

A hyphen indicates that the next word on the command line is a parameter. The most common parameter is Identity. For more information about parameters, see "Parameters" earlier in this white paper.

< >

Angle brackets are used to enclose parameter values. These values can be choices or names. For example, in -Parameter1 <1 | 2 | 3>, the numbers represent specific value choices. In -Parameter2 <ServerName>, ServerName represents the actual value.

[ ]

Square brackets are used to enclose an optional parameter and its value. A parameter and its value that are not enclosed in square brackets are required.

|

When the pipe symbol is used in a parameter value list, such as -Parameter1 <1 | 2 | 3>, it indicates a choice between available values. This convention applies to System.Enum parameters and System.Boolean parameters.

These command conventions help you understand how a command should be constructed. You don't type these conventions when you enter the command on the command line.

In the Exchange Help documentation, all cmdlets display their associated parameters in parameter sets. Parameter sets are groupings of parameters that can be used with each other. Parameters that exist in one parameter set, but not in another parameter set, are mutually exclusive. They can't be used together.

Although all cmdlets have parameter sets, many only have one set of parameters. This means that all the parameters on that cmdlet can be used with each other. Other cmdlets may have several parameter sets. The following example displays the parameter sets that are available on the New-SystemMessage cmdlet:

New-SystemMessage -DsnCode <EnhancedStatusCode> -Internal <$true | $false>
-Language <CultureInfo> -Text <String> [-DomainController <String>] [-Templ
ateInstance <MshObject>]

New-SystemMessage -Language <CultureInfo> -QuotaMessageType <WarningMailbox
UnlimitedSize | WarningPublicFolderUnlimitedSize | WarningMailbox | Warning
PublicFolder | ProhibitSendMailbox | ProhibitPostPublicFolder | ProhibitSen
dReceiveMailBox> -Text <String> [-DomainController <String>] [-TemplateInst
ance <MshObject>]

The New-SystemMessage cmdlet has two parameter sets. The first parameter set contains the DsnCode parameter and Internal parameter, and the second parameter set contains the QuotaMessageType parameter. This means that the DsnCode parameter and Internal parameter can be used with each other. But they can't be used with the QuotaMessageType parameter. The remaining parameters, Language, Text, DomainController, and TemplateInstance, are listed in both parameter sets. This means that they can be used with the DsnCode parameter and Internal parameter and with the QuotaMessageType parameter.

Parameter sets can indicate that a single cmdlet may have multiple uses. For example, you can use the New-SystemMessage cmdlet to configure customized delivery status notification (DSN) messages or configure customized mailbox quota limit messages. However, cmdlets typically have multiple parameter sets because one parameter may perform a function that is incompatible with another parameter. For example, the following example displays the parameter sets for the New-AddressList cmdlet:

New-AddressList -Name <String> [-Company <MultiValuedProperty>] [-Container
 <AddressListIdParameter>] [-Department <MultiValuedProperty>] [-DisplayNam
e <String>] [-DomainController <String>] [-IncludedRecipients <Nullable>] [
-StateOrProvince <MultiValuedProperty>] [-TemplateInstance <MshObject>]

New-AddressList -Name <String> [-Container <AddressListIdParameter>] [-Disp
layName <String>] [-DomainController <String>] [-RecipientFilter <String>]
[-TemplateInstance <MshObject>] 

In the New-AddressList cmdlet, the first parameter set lists parameters that let you create a new address list based on values supplied to the Company, Department, IncludedRecipients, and StateOrProvice parameters. However, you can also create a new address list by using a custom filter that is specified with the RecipientFilter parameter. When you create a new address list, a custom filter that was specified by using the RecipientFilter parameter overrides anything that was configured by using the parameters that exist in the first parameter set. Therefore, the RecipientFilter parameter is put in its own parameter set. Exchange 2007 doesn't let you specify both parameters on the same command line. As with the New-SystemMessage cmdlet, the remaining parameters that exist in both parameters sets in the New-AddressList cmdlet can be used in any combination.

Double quotation marks (") are most commonly used to enclose a value that has spaces when you pass that value to a parameter. For example, if you want to pass Contoso Receive Connector to the Name parameter of the Set-ReceiveConnector cmdlet, you must enclose Contoso Receive Connector in quotation marks as in the following example:

Set-ReceiveConnector -Name "Contoso Receive Connector"

If you don't enclose the string in quotation marks, the Exchange Management Shell tries to interpret each word in the string as a new argument on the command line and displays an error.

In the Exchange Management Shell, double quotation marks and single quotation marks (') have different meanings. When you enclose a string in double quotation marks, the Exchange Management Shell replaces any variables with a matching value. For example, assume the value ServerName is assigned to the variable $Server. Then, assume the following command is entered on the command line:

"$Server Example"

The following output is displayed:

ServerName Example

The variable $Server is replaced by the value ServerName in the output.

When you enclose a string in single quotation marks, the Exchange Management Shell doesn't try to replace variables with a matching value. Assume the variable $Server is still assigned the value ServerName. Then assume the following command is entered on the command line:

'$Server-Example'

The following output is displayed:

$Server-Example

The variable $Server has not been replaced with a value because the Exchange Management Shell doesn't interpret variables that are included in text that is enclosed in single quotation marks.

For more information about variables, see the "User-Defined Variables" and "Shell Variables" sections later in this white paper.

You may also need to display some characters, such as the dollar sign ($), double or single quotation marks, or back quotation mark (`). These characters have special meanings when used in the Exchange Management Shell. To instruct the Exchange Management Shell not to interpret these characters and to display them when they are included in a string enclosed with double quotation marks, you must use the back quotation mark escape character (`). For example, type the following on the command line:

"The price is `$23."

The following output is displayed:

The price is $23.

Because we used the escape character with the dollar sign, the Exchange Management Shell doesn't interpret the $ as the beginning of a variable.

If you enclose a string in single quotation marks, you don't have to escape any character unless you want to display a single quotation mark within a string. If you want to display a single quotation mark within a string that is enclosed in single quotation marks, you must use two single quotation marks (''). For example, type the following on the command line:

'Don''t confuse two single quotation marks with a double quotation mark!'

The following output is displayed:

Don't confuse two single quotation marks with a double quotation mark!

Use the operators in Table 13 when you type commands in the Exchange Management Shell. Some of the operators may match some of the previously mentioned command conventions. But they don't have the same meaning when they are typed on the command line. Table 13 shows the valid operators that you can use in a command.

Table 13   Exchange Management Shell command operators

Operator Description

=

The equal sign is used as an assignment character. The value on the right side of the equal sign is assigned to the variable on the left side of the equal sign. The following characters are also assignment characters:

  • +=   Add the value on the right side of the equal sign to the current value that is contained in the variable on the left side of the equal sign.

  • -=   Subtract the value on the right side of the equal sign from the current value that is contained in the variable on the left side of the equal sign.

  • *=   Multiply the current value of the variable on the left side of the equal sign by the value that is specified on the right side of the equal sign.

  • /=   Divide the current value of the variable on the left side of the equal sign by the value that is specified on the right side of the equal sign.

  • %=   Modify the current value of the variable on the left side of the equal sign by the value that is specified on the right side of the equal sign.

:

A colon can be used to separate a parameter's name and the parameter's value, as in the following example: -Enabled:$True. The use of a colon is optional with all parameter types except switch parameters. For more information about switch parameters, see "Parameters" earlier in this white paper.

!

The exclamation point is a logical NOT operator. When it is used with the equal ( ) sign, the combined pair means "not equal to."

[ ]

Brackets are used to specify the index value of an array position. For example, $Red[9] refers to the tenth index position in the array, $Red. It refers to the tenth index position because array indexes start at zero ( 0 ).

Brackets can also be used to assign a type to a variable, as in the following example: $A=[XML] "<Test><A>value</A></Test>". The following types are valid: Array, Bool, Byte, Char, Char[], Decimal, Double, Float, Int, Int[], Long, Long[], RegEx, Single, ScriptBlock, String, Type, and XML.

{ }

Braces are used to include an expression in a command, as in the following example: Get-Process | Where { $_.HandleCount -gt 400 }

|

The pipe symbol is used when one cmdlet pipes a result to another cmdlet. For example, the following command pipes the results from the Get-Mailbox cmdlet to the Move-Mailbox cmdlet: Get-Mailbox -Server SRV1 | Move-Mailbox -TargetDatabase SRV2

>

The right-angle bracket is used to send the output of a command to a file, as in the following example: Get-TransportRulePredicate > c:\out.txt. The destination file is overwritten.

>>

Double right-angle brackets are used to append the output of a command to a file, if the file exists. If the file does not exist, a new file is created. The following is an example of how to use double right-angle brackets: Get-TransportRulePredicate >>c:\out.txt

" "

' '

Quotation marks are used to enclose a string that contains spaces and also to determine how variables are interpreted in a string. For more information, see the "Use of Quotation Marks" section earlier in this white paper.

$

A dollar sign indicates a variable. For example, $Blue = 10 assigns the value 10 to the variable $Blue.

@

The @ symbol references an associative array. For more information, see "Arrays" later in this white paper.

$( )

A dollar sign ( $ ) with parentheses indicates command substitution. You can use command substitution when you want to use the output of one command as an argument in another command, as in the following example: Get-ChildItem $(Read-Host -Prompt "Enter FileName: ")

..

Double-periods indicate a value range. For example, if an array contains several indexes, you can specify the following command to return the values of all indexes between the second and fifth indexes, as in the following example: $Blue[2..5]

+

The + operator adds two values together. For example, 6 + 6 equals 12.

-

The - operator subtracts one value from another value. For example, 12 - 6 equals 6.

The - operator can also be used to represent a negative number, such as -6. For example, -6 * 6 equals -36.

*

A wildcard character has several meanings. You can use wildcard characters to match strings, to multiply numeric values, or, if strings and numeric values are used together, to repeat the string value the number of times that is specified by the numeric value, as in the following example: "Test" * 3 equals TestTestTest.

/

The / operator divides one value by another. For example, 6 / 6 equals 1.

%

The % operator returns the remainder from a division operator. For example, 6 % 4 equals 2.

Return to top

Pipelining in the Exchange Management Shell is the act of one cmdlet using the output of another cmdlet when it performs an operation. Pipelining is accomplished by using the pipe "|" symbol. All verbs in the same noun-cmdlet set can use piped information from another command. Some noun-cmdlet sets also let you pass data through the pipeline to another noun cmdlet set.

The use of pipelining to string together the actions of two or more cmdlets gives the Exchange Management Shell the power of composition, which lets you take smaller components and convert them into something more powerful. For example, you can use one cmdlet to gather data, pass that data to a second cmdlet to filter the data to a subset, and then pass that data to a third cmdlet to act on the subset only.

For example, the following command uses pipelining to move all the mailboxes on Server1 to the Executives database on Server2 by using the Move-Mailbox cmdlet, based on output that is piped from the Get-Mailbox cmdlet:

Get-Mailbox -Server Server1 | Move-Mailbox -TargetDatabase Server2\Executives

You can also use pipelining to process data that is output by a cmdlet. For example, for a list of all processes where the HandleCount property of the process is larger than 400, you can run the following command:

Get-Process | Where { $_.HandleCount -gt 400 } | Format-List

In this example, the Get-Process cmdlet passes objects to the Where-Object cmdlet. The Where-Object cmdlet picks out the objects that have a property called HandleCount with a value larger than 400.

In this example, the HandleCount property is preceded by the $_ variable. This variable is created automatically by the Exchange Management Shell to store the current pipeline object. The Where-Object cmdlet then sends these objects to the Format-List cmdlet to be displayed.

The use of structured objects, instead of text, is one of the most exciting capabilities of the Exchange Management Shell. The use of structured objects forms the basis of a powerful compositional model of administration.

For more information about structured objects, see "Structured Data" later in this white paper.

To report errors, you can use the error pipeline. The error pipeline lets you report errors while a command runs. This means that you don't have to wait until the command has finished running or to put the error information in the standard result pipeline. The Write-Error cmdlet writes its arguments to the error pipeline.

For more information about pipelining, run the following command in the Exchange Management Shell:

Get-Help About_Pipeline

Return to top

The Exchange Management Shell is a very powerful and flexible management interface. You can manage your infrastructure interactively by using the command line. You can create and run scripts that automate frequently used or complex tasks. As you learn how to use the Exchange Management Shell itself, scripting, or both, you may want to view the results of a command before the command affects data. Also, you may want to acknowledge that a command is about to run. This functionality is especially important as you transition from your test environment into your production environment and as you roll out new scripts or commands.

Both experienced administrators and script writers, and administrators who are new to Exchange and scripting, can benefit from using the WhatIf, Confirm, and ValidateOnly parameters. These parameters are available in the Exchange Management Shell. These parameters let you control how your commands run and indicate exactly what a command will do before it affects data. The WhatIf, Confirm, and ValidateOnly parameters are especially useful when you use them with commands that modify objects that are returned by using a filter or by using a Get command in a pipeline. This topic describes each parameter.

importantImportant:
If you want to use the WhatIf, Confirm, and ValidateOnly parameters with commands in a script, you must add the appropriate parameter to each command in the script, and not on the command line that calls the script.
noteNote:
The WhatIf, Confirm, and ValidateOnly parameters are called switch parameters. For more information about switch parameters, see "Parameters" earlier in this white paper.

The WhatIf parameter instructs the command to which it is applied to run but only to display the objects that would be affected by running the command and what changes would be made to those objects. The domain does not actually change any of those objects. When you use the WhatIf parameter, you can see whether the changes that would be made to those objects match your expectations, without the worry of modifying those objects.

When you run a command together with the WhatIf parameter, you put the WhatIf parameter at the end of the command, as in the following example:

New-AcceptedDomain -Name "Contoso Domain" -DomainName "contoso.com" -WhatIf 

When you run this example command, the following text is returned by the Exchange Management Shell:

What if: Creating Accepted Domain "Contoso Domain" with Domain Name "contoso.com".

To display a list of cmdlets that accept the WhatIf parameter, type the following command in the Exchange Management Shell:

Get-ExCommand | Where { $_.Definition -Like "*WhatIf*" }

The Confirm parameter instructs the command to which it is applied to stop processing before any changes are made. The command then prompts you to acknowledge each action before it continues. When you use the Confirm parameter, you can step through changes to objects to make sure that changes are made only to the specific objects that you want to change. This functionality is useful when you apply changes to many objects and want precise control over the operation of the Exchange Management Shell. A confirmation prompt is displayed for each object before the Exchange Management Shell modifies the object.

By default, the Exchange Management Shell automatically applies the Confirm parameter to cmdlets that have the following verbs:

  • Remove

  • Move

  • Stop

  • Clear

  • Suspend

  • Uninstall

  • Dismount

  • Disable

When a cmdlet runs that has any of these verbs, the Exchange Management Shell automatically stops the command and waits for your acknowledgement before it continues to process.

When you manually apply the Confirm parameter to a command, include the Confirm parameter at the end of the command, as in the following example:

Get-JournalRule | Enable-JournalRule -Confirm

When you run this example command, the following confirmation prompt is returned by the Exchange Management Shell:

[Y] Yes   [A] Yes to All   [N] No   [L] No to All   [S] Suspend   [?] Help   
(default is "Y"):

The confirmation prompt gives you the following choices:

  • [Y] Yes   Type Y to instruct the command to continue the operation. The next operation will present another confirmation prompt. [Y] Yes is the default choice.

  • [A] Yes to All   Type A to instruct the command to continue the operation and all subsequent operations. You will not receive additional confirmation prompts for the duration of this command.

  • [N] No   Type N to instruct the command to skip this operation and continue with the next operation. The next operation will present another confirmation prompt.

  • [L] No to All   Type L to instruct the command to skip this operation and all subsequent operations.

  • [S] Suspend   Type S to pause the current pipeline and return to the command line. Type Exit to resume the pipeline.

  • [?] Help   Type ? to display confirmation prompt help on the command line.

If you want to override the default behavior of the Exchange Management Shell and suppress the confirmation prompt for cmdlets on which it is automatically applied, you can include the Confirm parameter with a value of $False, as in the following example:

Get-JournalRule | Disable-JournalRule -Confirm:$False

In this case, no confirmation prompt is displayed.

CautionCaution:
The default value of the Confirm parameter is $True. The default behavior of the Exchange Management Shell is to automatically display a confirmation prompt. If you suppress this default behavior of the Exchange Management Shell, you instruct the command to suppress all confirmation prompts for the duration of that command. The command will process all objects that meet the criteria for the command without confirmation.

To display a list of cmdlets that accept the Confirm parameter, type the following command in the Exchange Management Shell:

Get-ExCommand | Where { $_.Definition -Like "*Confirm*" }

The ValidateOnly parameter instructs the command to which it is applied to evaluate all the conditions and requirements that are needed to perform the operation before you apply any changes. The ValidateOnly parameter is available on cmdlets that may take a long time to run, have several dependencies on multiple systems, or affect critical data, such as mailboxes.

When you apply the ValidateOnly parameter to a command, the command runs through the whole process. The command performs each action as it would without the ValidateOnly parameter. But the command doesn't change any objects. When the command completes its process, it displays a summary with the results of the validation. If the validation indicates that the command was successful, you can run the command again without the ValidateOnly parameter.

When you run a command together with the ValidateOnly parameter, you put the ValidateOnly parameter at the end of the command, as in the following example:

Get-Mailbox "Kim Akers" | Move-Mailbox -TargetDatabase "Executive Database" -ValidateOnly

When you run this example command, the following text is returned by the Exchange Management Shell:

Identity                         : contoso.com/Users/Kim Akers
DistinguishedName                : CN=Kim Akers,CN=Users,DC=contoso,DC=com
DisplayName                      : Kim Akers
Alias                            : kim
LegacyExchangeDN                 : /o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=kim
PrimarySmtpAddress               : kim@contoso.com
SourceServer                     : Win2003MS.contoso.com
SourceDatabase                   : WIN2003MS\First Storage Group\Mailbox Database
SourceGlobalCatalog              : Win2003MS.contoso.com
TargetGlobalCatalog              : Win2003MS.contoso.com
TargetDomainController           : Win2003MS.contoso.com
TargetMailbox                    :
TargetServer                     : Win2003MS.contoso.com
TargetDatabase                   : WIN2003MS\Second Storage Group\Executive Database
MailboxSize                      : 0KB
IsResourceMailbox                : False
SIDUsedInMatch                   :
SMTPProxies                      :
SourceManager                    :
SourceDirectReports              :
SourcePublicDelegates            :
SourcePublicDelegatesBL          :
MatchedTargetNTAccountDN         :
IsMatchedNTAccountMailboxEnabled :
MatchedContactsDNList            :
TargetNTAccountDNToCreate        :
TargetManager                    :
TargetDirectReports              :
TargetPublicDelegates            :
TargetPublicDelegatesBL          :
Options                          : Default
SourceForestCredential           :
TargetForestCredential           :
TargetFolder                     :
RsgMailboxGuid                   :
RsgMailboxLegacyExchangeDN       :
RsgMailboxDisplayName            :
RsgDatabaseGuid                  :
MoveType                         : IntraOrg
MoveStage                        : Validation
StartTime                        : 7/17/2006 4:39:13 PM
EndTime                          : 7/17/2006 4:39:14 PM
StatusCode                       : 0
StatusMessage                    : This mailbox can be moved to the target database.

To display a list of cmdlets that accept the ValidateOnly parameter, type the following command in the Exchange Management Shell:

Get-ExCommand | Where { $_.Definition -Like "*ValidateOnly*" }

Return to top

This section explains how to use the Exchange Management Shell to add values to and remove values from a multivalued property on an object.

A multivalued property is a property that can contain more than one value. For example, the BlockedRecipients property on the RecipientFilterConfig object can accept multiple recipient addresses as in the following examples:

  • john@contoso.com

  • kim@northwindtraders.com

  • david@adatum.com

Because the BlockedRecipients property can accept more than one value, it's called a multivalued property.

For more information about objects, see "Structured Data" later in this white paper..

How you modify a multivalued property is slightly different from how you modify a property that accepts only one value. When you modify a property that accepts only a single value, you can assign a value directly to it, as in the following command:

Set-TransportConfig -MaxSendSize 12MB

When you use this command to provide a new value to the MaxSendSize property, the stored value is overwritten. This isn't a problem with properties that accept only one value. However, it becomes a problem with multivalued properties. For example, assume that the BlockedRecipients property on the RecipientFilterConfig property is configured to have the three values that are listed in the previous section. When you run the command Get-RecipientFilterConfig | Format-List BlockedRecipients, the following is displayed:

BlockedRecipients : {david@adatum.com, kim@northwindtraders.com, john@contoso.com}

Now assume that you've received a request to add a new Simple Mail Transfer Protocol (SMTP) address to the blocked recipients list. You run the following command to add the new SMTP address:

Set-RecipientFilterConfig -BlockedRecipients chris@contoso.com

When you run the Get-RecipientFilterConfig | Format-List BlockedRecipients command again, you will see the following:

BlockedRecipients : {chris@contoso.com}

This isn't what you expected. You wanted to add the new SMTP address to the existing list of blocked recipients, but instead the existing list of blocked recipients was overwritten by the new SMTP address. This is how modifying a multivalued property differs from modifying a property that accepts only a single value. When you modify a multivalued property, you must make sure that you append or remove values instead of overwriting the whole list of values. The following sections show you how to do exactly that.

noteNote:
Some cmdlets, such as Set-TransportRule, do not support modifying properties on objects in the manner described in this topic. For more information about how to add values to and remove values from the multivalued properties of these cmdlets, see the topics for those cmdlets, such as Set-TransportRule.

To modify multivalued properties, you must understand the following concepts, which are explained elsewhere in this white paper. Be sure to review these sections.

  • User-Defined Variables

  • Pipelining

  • Syntax

  • Working with Command Output

Appending a value to a multivalued property is very simple. It just takes a few extra steps. Again, assume that the BlockedRecipients property contains the values that are listed in the first part of this section.

First, you have to retrieve the object that you want to modify and assign it to a variable. For example, use the following command to assign the RecipientFilterConfig object to the variable $Example:

$Example = Get-RecipientFilterConfig

If you run the command $Example | Format-List BlockedRecipients, the following is returned:

BlockedRecipients : {david@adatum.com, kim@northwindtraders.com, john@contoso.com}

Next, you have to add the value that you want to append to the BlockedRecipients property on the object that is stored in the variable $Example. Be aware that this step only adds the value to the object that is stored in the variable. To add chris@contoso.com to the BlockedRecipients property on the object that is stored in the variable $Example, run the following command:

$Example.BlockedRecipients += "chris@contoso.com"

If you run the command $Example | Format-List BlockedRecipients again, the following is returned:

BlockedRecipients : {david@adatum.com, kim@northwindtraders.com, john@contoso.com, chris@contoso.com}

As you can see, the SMTP address chris@contoso.com has been added to the list of values that are stored in the BlockedRecipients property.

Finally, you have to save the object that is stored in $Example by using the following command:

Set-RecipientFilterConfig -BlockedRecipients $Example.BlockedRecipients

Now, when you run the Get-RecipientFilterConfig | Format-List BlockedRecipients command, you will see that the SMTP address chris@contoso.com has been added to the server.

If you want to append many values at the same time to a multivalued property, perform the same step as described earlier. When you specify the values that you want to append, separate the values by using commas as in the following example:

$Example.BlockedRecipients += "user1@contoso.com", "user2@contoso.com", "user3@contoso.com"

After you have specified the values that you want to add, use the Set-RecipientFilterConfig cmdlet to save the object.

noteNote:
Some cmdlets don't let you append multiple values at the same time.

Chances are that you may want to remove only one value from a multivalued property instead of removing all the values at the same time. Removing a value from a multivalued property is like appending a value. However, unlike appending values, you must remove values one at a time. Again, assume that the BlockedRecipients property contains the values that are listed in the first section.

First, you must assign the object that you want to modify to a variable, as in the following example:

$Example = Get-RecipientFilterConfig

Then, run the following command, which specifies the exact value that you want to remove:

$Example.BlockedRecipients -= "david@contoso.com"

Finally, save the object that is stored in the variable as follows:

Set-RecipientFilterConfig -BlockedRecipients $Example.BlockedRecipients

The following Exchange Management Shell procedures are examples of how to append values to some of the multivalued properties that are available on various objects in Exchange 2007.

To append an SMTP address to a mailbox
  1. Run the following commands:

    $Mailbox = Get-Mailbox "Kim Akers"
    $Mailbox.EmailAddresses += "kim@contoso.com"
    Set-Mailbox "Kim Akers" -EmailAddresses $Mailbox.EmailAddresses
    
  2. Run the following command to view the updated mailbox:

    Get-Mailbox "Kim Akers" | Format-List Name, EmailAddresses
    
To append additional delivery status notification (DSN) codes on the GenerateCopyOfDSNFor property
  1. Run the following commands:

    $DsnList = Get-TransportConfig
    $DsnList.GenerateCopyOfDSNFor += "5.4.7", "5.7.1", "5.7.2"
    Set-TransportConfig -GenerateCopyOfDSNFor $DsnList.GenerateCopyOfDSNFor
    
  2. Run the following command to view the updated DSN codes:

    Get-TransportConfig | Format-List GenerateCopyOfDSNFor
    

The following procedures are examples of how to remove values from some of the multivalued properties that are available on various objects in Exchange 2007.

To remove the device ID of an enabled Exchange ActiveSync device from a Client Access server (CAS) mailbox
  1. Run the following commands

    $CasDevice = Get-CasMailbox "David Simpson"
    $CasDevice.ActiveSyncAllowedDeviceIDs -= "4B9207650054767AD0AEE83A414BCD7F"
    Set-CasMailbox "David Simpson" -ActiveSyncAllowedDeviceIDs $CasDevice.ActiveSyncAllowedDeviceIDs
    
  2. Run the following command to view the updated CAS mailbox:

    Get-CasMailbox "David Simpson" | Format-List Name, ActiveSyncAllowedDeviceIDs
    
To remove a mailbox from the list of mailboxes that are granted "send on behalf of" permissions on a distribution group
  1. Run the following command:

    $DistributionGroup = Get-DistributionGroup "Sales Group"
    $DistributionGroup.GrantSendOnBehalfTo -= (Get-Maibox "Christine Hughes").Identity
    Set-DistributionGroup "Sales Group" -GrantSendOnBehalfTo $DistributionGroup.GrantSendOnBehalfTo
    
  2. Run the following command to view the updated distribution group

    Get-DistributionGroup "Sales Group" | Format-List Name, GrantSendOnBehalfTo
    

The Exchange Management Shell offers several methods that you can use to format command output. This topic discusses the following subjects:

  • How to format data   Control how the data that you see is formatted by using the Format-List, Format-Table, and Format-Wide cmdlets.

  • How to output data   Determine whether data is output to the Exchange Management Shell console window or to a file by using the Out-Host and Out-File cmdlets. Included in this section is a sample script to output data to Internet Explorer.

  • How to filter data   Filter data by using either of the following filtering methods:

    • Server-side filtering, available on certain cmdlets

    • Client-side filtering, available on all cmdlets by piping the results of a command to the Where-Object cmdlet

To use the functionality that is described in this section, you must be familiar with the following concepts, which are explained elsewhere in this white paper:

  • Pipelining

  • Shell Variables

  • Comparison Operators

If you call formatting cmdlets at the end of the pipeline, you can override the default formatting to control what data is displayed and how that data appears. The formatting cmdlets are Format-List, Format-Table, and Format-Wide. Each has its own distinct output style that differs from the other formatting cmdlets.

The Format-List cmdlet takes input from the pipeline and outputs a vertical columned list of all the specified properties of each object. You can specify which properties you want to display by using the Property parameter. If the Format-List cmdlet is called without any parameters specified, all properties are output. The Format-List cmdlet wraps lines instead of truncating them. One of the best uses for the Format-List cmdlet is to override the default output of a cmdlet so that you can retrieve additional or more focused information.

For example, when you call the Get-Mailbox cmdlet, you only see a limited amount of information in table format. If you pipe the output of the Get-Mailbox cmdlet to the Format-List cmdlet and add parameters for the additional or more focused information that you want to view, you can retrieve the output that you want.

You can also specify a wildcard character "*" with a partial property name. If you include a wildcard character, you can match multiple properties without having to type each property name individually. For example, Get-Mailbox | Format-List -Property Email* returns all properties that begin with Email.

The following examples show the different ways that you can view the same data returned by the Get-Mailbox cmdlet.

Get-MailBox TestUser1

Name                      Alias                Server           StorageQuota
----                      -----                ------           ------------
TestUser1                  TestUser1             e12           unlimited

In this first example, the Get-Mailbox cmdlet is called without specific formatting so the default output is in table format and contains a predetermined set of properties.

Get-Mailbox TestUser1 | Format-List -Property Name,Alias,EmailAddresses

Name           : TestUser1
Alias          : TestUser1
EmailAddresses : {SMTP:TestUser1@contoso.com, X400:c=US;a= ;p=Contoso;o=Exchange;s=TestUser1;}

In the second example, the output of the Get-Mailbox cmdlet is piped to the Format-List cmdlet, together with specific properties. As you can see, the format and content of the output is significantly different.

Get-Mailbox TestUser1 | Format-List -Property Name, Alias, Email*

Name                      : Test User
Alias                     : TestUser1
EmailAddresses            : {SMTP:TestUser1@contoso.com, X400:c=US;a= ;p=First
                            Organization;o=Exchange;s=User;g=Test;}
EmailAddressPolicyEnabled : True

In the last example, the output of the Get-Mailbox cmdlet is piped to the Format-List cmdlet as in the second example. However, in the last example, a wildcard character is used to match all properties that start with Email.

If more than one object is passed to the Format-List cmdlet, all specified properties for an object are displayed and grouped by object. The display order depends on the default parameter for the cmdlet. This is most frequently the Name parameter or the Identity parameter. For example, when the Get-Childitem cmdlet is called, the default display order is file names in alphabetical order. To change this behavior, you must call the Format-List cmdlet, together with the GroupBy parameter, and the name of a property value by which you want to group the output. For example, the following command lists all files in a directory and groups these files by extension.

Get-Childitem | Format-List Name,Length -GroupBy Extension

    Extension: .xml

Name   : Config_01.xml
Length : 5627

Name   : Config_02.xml
Length : 3901


    Extension: .bmp

Name   : Image_01.bmp
Length : 746550

Name   : Image_02.bmp
Length : 746550


    Extension: .txt

Name   : Text_01.txt
Length : 16822

Name   : Text_02.txt
Length : 9835

In this example, the Format-List cmdlet has grouped the items by the Extension property that is specified by the GroupBy parameter. You can use the GroupBy parameter with any valid property for the objects in the pipeline stream.

The Format-Table cmdlet lets you display items in a table format with label headers and columns of property data. By default, many cmdlets, such as the Get-Process and Get-Service cmdlets, use the table format for output. Parameters for the Format-Table cmdlet include the Properties and GroupBy parameters. These work exactly as they do with Format-List cmdlet.

The Format-Table cmdlet also uses the Wrap parameter. This enables long lines of property information to display completely instead of truncating at the end of a line. To see how the Wrap parameter is used to display returned information, compare the output of the Get-Command command in the following two examples.

In the first example, when the Get-Command cmdlet is used to display command information about the Get-Process cmdlet, the information for the Definition property is truncated.

Get-Command Get-Process | Format-Table Name,Definition

Name                                    Definition
----                                    ----------
get-process                             get-process [[-ProcessName] String[]...

In the second example, the Wrap parameter is added to the command to force the complete contents of the Definition property to display.

Get-Command Get-Process | Format-Table Name,Definition -Wrap

Name                                    Definition
----                                    ----------
get-process                             get-process [[-ProcessName] String[]] [
                                        -Verbose] [-Debug] [-ErrorAction Action
                                        Preference] [-ErrorVariable String] [-O
                                        utVariable String] [-OutBuffer Int32]
                                        get-process -Id Int32[] [-Verbose] [-De
                                        bug] [-ErrorAction ActionPreference] [-
                                        ErrorVariable String] [-OutVariable Str
                                        ing] [-OutBuffer Int32]
                                        get-process -Input Process[] [-Verbose]
                                         [-Debug] [-ErrorAction ActionPreferenc
                                        e] [-ErrorVariable String] [-OutVariabl
                                        e String] [-OutBuffer Int32] 

As with the Format-List cmdlet, you can also specify a wildcard character "*" with a partial property name. By including a wildcard character, you can match multiple properties without typing each property name individually.

The Format-Wide cmdlet provides a much simpler output control than the other format cmdlets. By default, the Format-Wide cmdlet tries to display as many columns of property values as possible on a line of output. By adding parameters, you can control the number of columns and how the output space is used.

In the most basic usage, calling the Format-Wide cmdlet without any parameters arranges the output in as many columns as will fit the page. For example, if you run the Get-Childitem cmdlet and pipe its output to the Format-Wide cmdlet, you will see the following display of information:

Get-ChildItem | Format-Wide

    Directory: FileSystem::C:\WorkingFolder

Config_01.xml                           Config_02.xml
Config_03.xml                           Config_04.xml
Config_05.xml                           Config_06.xml
Config_07.xml                           Config_08.xml
Config_09.xml                           Image_01.bmp
Image_02.bmp                            Image_03.bmp
Image_04.bmp                            Image_05.bmp
Image_06.bmp                            Text_01.txt
Text_02.txt                             Text_03.txt
Text_04.txt                             Text_05.txt
Text_06.txt                             Text_07.txt
Text_08.txt                             Text_09.txt
Text_10.txt                             Text_11.txt
Text_12.txt

Generally, calling the Get-Childitem cmdlet without any parameters displays the names of all files in the directory in a table of properties. In this example, by piping the output of the Get-Childitem cmdlet to the Format-Wide cmdlet, the output was displayed in two columns of names. Notice that only one property type can be displayed at a time, specified by a property name that follows the Format-Wide cmdlet. If you add the Autosize parameter, the output is changed from two columns to as many as can fit the screen width.

Get-ChildItem | Format-Wide -AutoSize

    Directory: FileSystem::C:\WorkingFolder

Config_01.xml   Config_02.xml   Config_03.xml   Config_04.xml   Config_05.xml
Config_06.xml   Config_07.xml   Config_08.xml   Config_09.xml   Image_01.bmp
Image_02.bmp    Image_03.bmp    Image_04.bmp    Image_05.bmp    Image_06.bmp
Text_01.txt     Text_02.txt     Text_03.txt     Text_04.txt     Text_05.txt
Text_06.txt     Text_07.txt     Text_08.txt     Text_09.txt     Text_10.txt
Text_11.txt     Text_12.txt

In this example, the table is arranged in five columns, instead of two columns. The Column parameter offers more control by letting you specify the maximum number of columns to display information as follows:

Get-ChildItem | Format-Wide -Columns 4

    Directory: FileSystem::C:\WorkingFolder

Config_01.xml       Config_02.xml       Config_03.xml       Config_04.xml
Config_05.xml       Config_06.xml       Config_07.xml       Config_08.xml
Config_09.xml       Image_01.bmp        Image_02.bmp        Image_03.bmp
Image_04.bmp        Image_05.bmp        Image_06.bmp        Text_01.txt
Text_02.txt         Text_03.txt         Text_04.txt         Text_05.txt
Text_06.txt         Text_07.txt         Text_08.txt         Text_09.txt
Text_10.txt         Text_11.txt         Text_12.txt

In this example, the number of columns is forced to four by using the Column parameter.

The Out-Host cmdlet is an unseen default cmdlet at the end of the pipeline. After all formatting is applied, the Out-Host cmdlet sends the final output to the console window for display. You don't have to explicitly call the Out-Host cmdlet, because it is the default output. You can override sending the output to the console window by calling the Out-Host cmdlet as the last cmdlet in the command. The Out-File cmdlet then writes the output to the file that you specify in the command as in the following example:

Get-ChildItem | Format-Wide -Columns 4 | Out-File c:\OutputFile.txt

In this example, the Out-Host cmdlet writes the information that is displayed in the Get-ChildItem | Format-Wide -Columns 4 command to a file that is named OutputFile.txt. You can also redirect pipeline output to a file by using the redirection operator, which is the right-angle bracket ( > ). To append pipeline output of a command to an existing file without replacing the original file, use the double right-angle brackets ( >> ), as in the following example:

Get-ChildItem | Format-Wide -Columns 4 >> C:\OutputFile.txt

In this example, the output from the Get-Childitem cmdlet is piped to the Format-Wide cmdlet for formatting and then is written to the end of the OutputFile.txt file. Notice that if the OutputFile.txt file did not exist, use of the double right-angle brackets ( >> ) would create the file.

For more information about pipelining, see "Pipelining" earlier in this white paper.

For more information about the syntax used in the previous examples, see "Syntax" earlier in this white paper.

Because of the flexibility and ease of scripting in the Exchange Management Shell, you can take the data that is returned by commands and format and output them in almost limitless ways.

The following example shows how you can use a simple script to output the data that is returned by a command and display it in Internet Explorer. This script takes the objects that are passed through the pipeline, opens an Internet Explorer window, and then displays the data in Internet Explorer:

$Ie = New-Object -Com InternetExplorer.Application
$Ie.Navigate("about:blank")
While ($Ie.Busy) { Sleep 1 }
$Ie.Visible = $True
$Ie.Document.Write("$Input")
# If the previous line doesn't work on your system, uncomment the line below.
# $Ie.Document.IHtmlDocument2_Write("$Input")
$Ie

To use this script, save it to the C:\Program Files\Microsoft\Exchange Server\Scripts directory on the computer where the script will be run. Name the file Out-Ie.ps1. After you save the file, you can then use the script as a regular cmdlet.

The Out-Ie script assumes that the data it receives is valid HTML. To convert the data that you want to view into HTML, you must pipe the results of your command to the ConvertTo-Html cmdlet. You can then pipe the results of that command to the Out-Ie script. The following example shows how to view a directory listing in an Internet Explorer window:

Get-ChildItem | Select Name,Length | ConvertTo-Html | Out-Ie

The Exchange Management Shell gives you access to a large quantity of information about your servers, mailboxes, Active Directory directory service, and other objects in your organization. Although access to this information helps you better understand your environment, this large quantity of information can easily overwhelm you. The Exchange Management Shell lets you control this information and return only the data that you want to see by using filtering. The following two types of filtering are available:

  • Server-side filtering   Server-side filtering takes the filter that you specify on the command line and submits it to the Exchange server that you query. That server processes the query and returns only the data that matches the filter that you specified.

    Server-side filtering is performed only on objects where tens or hundreds of thousands of results could be returned. Therefore, only the recipient management cmdlets, such as the Get-Mailbox cmdlet, and queue management cmdlets, such as the Get-Queue cmdlet, support server-side filtering. These cmdlets support the Filter parameter. This takes the filter expression that you specify and submits it to the server for processing.

  • Client-side filtering   Client-side filtering is performed on the objects in the local console window in which you are currently working. When you use client-side filtering, the cmdlet retrieves all the objects that match the task that you are performing to the local console window. The Exchange Management Shell then takes all the returned results, applies the client-side filter to those results, and returns to you only the results that match your filter. All cmdlets support client-side filtering. This is invoked by piping the results of a command to the Where-Object cmdlet.

The implementation of server-side filtering is specific to the cmdlet on which it is supported. Server-side filtering is enabled only on specific properties on the objects that are returned.

For more information about how to manage recipients by using server-side filtering, see "Creating Filters in Recipient Commands" in Exchange Server 2007 Help.

For more information about how to manage queues by using server-side filtering, see "Filtering Queues" in Exchange Server 2007 Help.

Client-side filtering can be used with any cmdlet. This includes those that also support server-side filtering. As described earlier in this section, client-side filtering accepts all the data that is returned by a previous command in the pipeline, and in turn, returns only the results that match the filter that you specify. The Where-Object cmdlet performs this filtering. It can be shortened to Where.

As data passes through the pipeline, the Where cmdlet receives the data from the previous object and then filters the data before passing it on to the next object. The filtering is based on a script block that is defined in the Where command. The script block filters data based on the object’s properties and values.

The Clear-Host cmdlet is used to clear the console window. In this example, you can find all the defined aliases for the Clear-Host cmdlet if you run the following command:

Get-Alias | Where {$_.Definition -eq "Clear-Host"}

CommandType     Name                            Definition
-----------     ----                            ----------
Alias           clear                           clear-host
Alias           cls                             clear-host

The Get-Alias cmdlet and the Where command work together to return the list of aliases that are defined for the Clear-Host cmdlet and no other cmdlets. Table 14 outlines each element of the Where command that is used in the example.

Table 14   Elements of the Where command

Element Description

{ }

Braces enclose the script block that defines the filter.

$_

This special variable automatically initiates and binds to the objects in the pipeline.

Definition

The Definition property is the property of the current pipeline objects that stores the name of the alias definition. When Definition is used with the $_ variable, a period comes before the property name.

-eq

This comparison operator for “equal to” is used to specify that the results must exactly match the property value that is supplied in the expression.

“Clear-Host”

In this example, “Clear-Host” is the value for which the command is parsing.

In the example, the objects that are returned by the Get-Alias cmdlet represent all the defined aliases on the system. Even though you don't see them from the command line, the aliases are collected and passed to the Where cmdlet through the pipeline. The Where cmdlet uses the information in the script block to apply a filter to the alias objects.

The special variable $_represents the objects that are being passed. The $_variable is automatically initiated by the shell and is bound to the current pipeline object. For more information about this special variable, see "Shell Variables" later in this white paper.

Using standard "dot" notation (object.property), the Definition property is added to define the exact property of the object to evaluate. The -eq comparison operator then compares the value of this property to "Clear-Host". Only the objects that have the Definition property that match this criterion are passed to the console window for output.

The Exchange Management Shell has a rich set of operators that enables comparisons of one object with another object or one object with a set of objects.

For more information about comparison operators, run the following command in the Exchange Management Shell:

Get-Help About_Comparison_Operators

Table 15 lists the comparison operators that are available in the Exchange Management Shell. Some comparison operators are case-sensitive. Other comparison operators are not case-sensitive. If a comparison operator is case-sensitive, the case that is used in the strings that are being compared must match. For example, the string "Test" does not match "test" when you use a comparison operator that is case-sensitive.

Table 15   Comparison operators that are available in the Exchange Management Shell

Operator Definition

-eq

Equals (not case-sensitive)

-ieq

Equals (not case-sensitive)

-ceq

Equals (case-sensitive)

-ne

Not equal (not case-sensitive)

-ine

Not equal (not case-sensitive)

-cne

Not equal (case-sensitive)

-lt

Less than (not case-sensitive)

-ilt

Less than (not case-sensitive)

-clt

Less than (case-sensitive)

-gt

Greater than (not case-sensitive)

-igt

Greater than (not case-sensitive)

-cgt

Greater than (case-sensitive)

-le

Less than or equal to (not case-sensitive)

-ile

Less than or equal to (not case-sensitive)

-cle

Less than or equal to (case-sensitive)

-ge

Greater than or equal to (not case-sensitive)

-ige

Greater than or equal to (not case-sensitive)

-cge

Greater than or equal to (case-sensitive)

-contains

The elements in the left operand that is equal to the right operand (not case-sensitive)

-icontains

The elements in the left operand that is equal to the right operand (not case-sensitive)

-ccontains

The elements in the left operand that is equal to the right operand (case-sensitive)

-notcontains

The elements in the left operand that is equal to the right operand (not case-sensitive)

-inotcontains

The elements in the left operand that is equal to the right operand (not case-sensitive)

-cnotcontains

The elements in the left operand that is equal to the right operand (case-sensitive)

-band

Bitwise And

-bor

Bitwise Or

-bnot

Bitwise NOT

-and

Logical and

-or

Logical or

-not

Logical not

-match

Compare strings by using regular expressions (not case-sensitive)

-notmatch

Compare strings by using regular expressions (not case-sensitive)

-imatch

Compare strings by using regular expressions (not case-sensitive)

-inotmatch

Compare strings by using regular expressions (not case-sensitive)

-cmatch

Compare strings by using regular expressions (case-sensitive)

-cnotmatch

Compare strings by using regular expressions (case-sensitive)

-like

Compare strings by using wildcard rules

-notlike

Compare strings by using wildcard rules

-ilike

Compare strings by using wildcard rules (not case-sensitive)

-inotlike

Compare strings by using wildcard rules (not case-sensitive)

-clike

Compare strings by using wildcard rules (case-sensitive)

-cnotlike

Compare strings by using wildcard rules (case-sensitive)

Return to top

In Exchange 2007, you can assign an Exchange Management Shell cmdlet or Cmd.exe command to an administrator-defined and easy-to-remember alias. Such aliases can be useful when you frequently use certain cmdlets and want to reduce the typing that you must do.

When an alias is called from the command line, the rules that apply to the cmdlet that is represented by the alias are enforced exactly as when the cmdlet is called. You must supply any required parameters and their values exactly as if you had called the cmdlet name.

Many cmdlets that are used regularly have default, or built-in, aliases assigned to them. These built-in aliases help reduce the typing that you have to do when you administer Exchange 2007 by using the Exchange Management Shell.

For example, the Get-ChildItem cmdlet resembles the MS-DOS Dir command. Because you are familiar with the Dir command, you might want to use the Dir alias when you use the Exchange Management Shell instead of typing Get-ChildItem every time that you want to view the contents of a directory. The output from the Get-ChildItem cmdlet and the Dir alias is the same and can be used interchangeably.

Table 16 shows the built-in aliases and their full names.

Table 16   Built-in aliases

Alias Command Alias Command Alias Command

Ac

Add-Content

Iex

Invoke-Expression

Write

Write-Output

Asnp

Add-PSSnapin

Ihy

Invoke-History

Cat

Get-Content

Clc

Clear-Content

Ii

Invoke-Item

Cd

Set-Location

Cli

Clear-Item

Ipal

Import-Alias

Clear

Clear-Host

Clp

Clear-ItemProperty

Ipcsv

Import-Csv

Cp

Copy-Item

Clv

Clear-Variable

Mi

Move-Item

H

Get-History

Cpi

Copy-Item

Mp

Move-ItemProperty

History

Get-History

Cpp

Copy-ItemProperty

Nal

New-Alias

Kill

Stop-Process

Cvpa

Convert-Path

Ndr

New-PSDrive

Lp

Out-Printer

Diff

Compare-Object

Ni

New-Item

Ls

Get-ChildItem

Epal

Export-Alias

Nv

New-Variable

Mount

New-PSDrive

Epcsv

Export-Csv

Oh

Out-Host

Mv

Move-Item

Fc

Format-Custom

Rdr

Remove-PSDrive

Popd

Pop-Location

Fl

Format-List

Ri

Remove-Item

Ps

Get-Process

Foreach

ForEach-Object

Rni

Rename-Item

Pushd

Push-Location

%

ForEach-Object

Rnp

Rename-ItemProperty

Pwd

Get-Location

Ft

Format-Table

Rp

Remove-ItemProperty

R

Invoke-History

Fw

Format-Wide

Rsnp

Remove-PSSnapin

Rm

Remove-Item

Gal

Get-Alias

Rv

Remove-Variable

Rmdir

Remove-Item

Gc

Get-Content

Rvpa

Resolve-Path

Echo

Write-Output

Gci

Get-ChildItem

Sal

Set-Alias

Cls

Clear-Host

Gcm

Get-Command

Sasv

Start-Service

Chdir

Set-Location

Gdr

Get-PSDrive

Sc

Set-Content

Copy

Copy-Item

Ghy

Get-History

Select

Select-Object

Del

Remove-Item

Gi

Get-Item

Si

Set-Item

Dir

Get-ChildItem

Gl

Get-Location

Sl

Set-Location

Erase

Remove-Item

Gm

Get-Member

Sleep

Start-Sleep

Move

Move-Item

Gp

Get-ItemProperty

Sort

Sort-Object

Rd

Remove-Item

Gps

Get-Process

Sp

Set-ItemProperty

Ren

Rename-Item

Group

Group-Object

Spps

Stop-Process

Set

Set-Variable

Gsv

Get-Service

Spsv

Stop-Service

Type

Get-Content

Gsnp

Get-PSSnapin

Sv

Set-Variable

List

Format-List

Gu

Get-Unique

Tee

Tee-Object

Table

Format-Table

Gv

Get-Variable

Where

Where-Object

Man

ExHelp

Gwmi

Get-WmiObject

?

Where-Object

Help

ExHelp

For more information about aliases, run the following command in the Exchange Management Shell:

Get-Help About_Alias

In addition to the default, or built-in, aliases, you can define and use custom aliases instead of the names of cmdlets that you frequently use. You can use the Set-Alias cmdlet to associate cmdlets to familiar command names that have the equivalent functionality in Cmd.exe. You can assign multiple aliases to a single command. But each alias can only be assigned to a single command. For example, you can have three aliases Alias1, Alias2, and Alias3 that are assigned to the Move-Mailbox cmdlet. You could then use any of the three aliases to run the Move-Mailbox cmdlet. However, each alias that you create can only be assigned to the Move-Mailbox cmdlet. You can't, for example, assign Alias1 to both the Move-Mailbox cmdlet and the Get-Mailbox cmdlet.

To create a new alias-cmdlet pairing, run the Set-Alias cmdlet and supply the name of the alias, together with the name of the cmdlet that you want to call when the alias is entered.

Table 17 shows several examples of how to create a new alias.

Table 17   Examples of custom aliases

Alias description Alias command

Retrieve the contents of a file.

Set-Alias Type Get-Content

Retrieve the listing of a directory.

Set-Alias Dir Get-ChildItem

Remove a file.

Set-Alias Erase Remove-Item

Set pad as an alias for Microsoft WordPad.

Set-Alias Pad "${env:programfiles}\Windows NT\Accessories\wordpad.exe"

Display the list of all defined aliases.

Set-Alias Aliases Get-Alias

To remove an alias, delete the alias from the alias drive. For example, an administrator creates the Ls alias by using the following command:

Set-Alias Ls Get-ChildItem

Later the administrator decides that the Ls alias is no longer needed and uses the following command to remove the Ls alias:

Remove-Item Alias Ls

The Export-Alias cmdlet writes the current alias list to a file in comma-separated values (CSV) format. You can include the name of the file and its path in the command line. If the path doesn't exist, the cmdlet will create the path for you. You can create the file by using the .txt or .doc extensions.

The Import-Alias cmdlet reads a text file that has CSV values and brings the list into the Exchange Management Shell as an object. By using the Export-Alias cmdlet and Import-Alias cmdlet, you can export a list of aliases from the Exchange Management Shell on one computer and import them to the Exchange Management Shell on another computer. Because existing predefined aliases exist on both computers, all alias name conflicts will be ignored and not imported.

Aliases that are created from the command line by using the Set-Alias cmdlet during an Exchange Management Shell session can be used when the session is active. After the session is closed, the alias definition is lost. To make a user-defined alias persistent and available every time that a new Exchange Management Shell session is opened, you must add the alias definition to the Exchange Management Shell Microsoft.PowerShell_Profile.ps1 file that is located in the My Documents\PSConfiguration subfolder of your user profile directory.

Although aliases can be defined for cmdlets and used instead of cmdlet names, you can't include parameters in the definition of the aliases that you define. You must provide parameters as needed when the alias is called, exactly as you would if you called the cmdlet.

Return to top

A variable is a location to store information. Unlike in many programming environments, in the Exchange Management Shell, you don't have to declare a variable before you use it.

You designate a variable by prepending a string with a dollar sign ($). You must enclose the string in braces ({ }) if the string contains spaces or other special characters. By using the array reference notation ([ ]), you can address the elements of an array or hash table variable.

For more information about arrays, see "Arrays" later in this white paper.

Variables are very useful if you want to store a value. You can assign values to variables by using an assignment operator. For more information about operators, see "Syntax" earlier in this white paper.

For example, to assign a value of 8 to the variable $Example, use the following command:

$Example = 8

This command assigns the integer 8 to the variable $Example. You can then call the $Example variable later in another command to recall the value. The values that are specified in a variable are treated exactly as if the value that it contains was typed in the location that the variable is specified. For example, the following two commands are equivalent if $Example2 is assigned the value "Hello":

Write-Host $Example2
Write-Host "Hello"

You can also store the output of commands in a variable for later use. When you assign a command to a variable, the command is evaluated at the time that command is run. The output of that command is assigned to the variable. For example, if you run $CurrentDate = Get-Date on the command line and then call $CurrentDate repeatedly over several seconds, the value that is reported is the same every time that the variable is called.

When you assign the output of a command to a variable, you can also access the properties and methods of the underlying object. For example, to view the properties and methods that are available when you assign Get-Date to $CurrentDate, you can use the $CurrentDate | Get-Member command. When you use the $CurrentDate | Get-Member command, the following properties are returned in a list:

Date                 Property       System.DateTime Date {get;}
Day                  Property       System.Int32 Day {get;}
DayOfWeek            Property       System.DayOfWeek DayOfWeek {get;}
DayOfYear            Property       System.Int32 DayOfYear {get;}
Hour                 Property       System.Int32 Hour {get;}
Kind                 Property       System.DateTimeKind Kind {get;}
Millisecond          Property       System.Int32 Millisecond {get;}
Minute               Property       System.Int32 Minute {get;}
Month                Property       System.Int32 Month {get;}
Second               Property       System.Int32 Second {get;}
Ticks                Property       System.Int64 Ticks {get;}
TimeOfDay            Property       System.TimeSpan TimeOfDay {get;}
Year                 Property       System.Int32 Year {get;}
DateTime             ScriptProperty System.Object DateTime {get=if ($this.Di...

You can then call any of these properties by typing the variable, a period (.), and then the property that you want to view. For example, to view the year that is stored on a variable, use the following command:

$CurrentDate.Year

By accessing the properties of a variable, you can easily manipulate and use each piece of information that is stored in the variable without the use of text parsing.

You can also store the output of the Dir command in a variable. Because the Dir command returns multiple rows when it runs, each row that is returned is stored in a variable as a new array element. You can then access each file object that is stored in the newly created array.

The following command assigns the output of the Dir command to the $DirOutput variable:

$DirOutput = Dir

You can then select a specific file object by specifying the array index that you want to view as follows:

$DirOutput[1].Name

Or you can create a simple loop that cycles through the whole array and displays the name and file size of each file that is stored in the array as follows:

0..$DirOutput.Length | ForEach { $DirOutput[$_].Name + " is " + $DirOutput[$_].Length + " bytes long." }

The following list examines this example:

  • The 0..$DirOutput.Length command instructs the Exchange Management Shell to output an integer from 0 to the maximum length of the array that is stored in the $DirOutput variable.

  • The output of the 0..$DirOutput.Length command is piped to the ForEach command that loops through each element of the array until it reaches the end of the array. The ForEach command runs the commands that are enclosed in the braces " { } ".

  • The $_ variable stores the current object that is in the pipeline. In this case, the object in the pipeline is an integer that is produced by the 0..$DirOutput.Length command as it counts from 0 to the maximum length of the array. This variable is used in the $DirOutput[$_].Name command and $DirOutput[$_].Length command to select the array element to access.

  • For more information about the $_ variable, see "Shell Variables" later in this white paper.

  • The plus " + " signs concatenate the output of the $DirOutput[$_].Name command and $DirOutput[$_].Length command, together with the strings supplied, to create output similar to the following:

    abv_dg.dll is 416144 bytes long.
    addxa.dll is 285056 bytes long.
    ASDat.MSI is 5626880 bytes long.
    ASEntDat.MSI is 5626880 bytes long.
    ASEntIRS.MSI is 910336 bytes long.
    ASEntSig.MSI is 45056 bytes long.
    BPA.Common.dll is 211848 bytes long.
    BPA.ConfigCollector.dll is 101272 bytes long.
    BPA.NetworkCollector.dll is 52128 bytes long.
    

These examples show that you can use the Length property more than one time to display different information about the same variable. You can do this because more than one type of data is stored in the $DirOutput variable. The first type of data is the directory object itself, and the second type of data is the file objects. When you run the $DirObject.Length command, without specifying an array index, you are accessing the directory parent object types that are stored in the array. When you specify an array index, such as $DirObject[5].Length, you are accessing the file child objects that are stored in the directory object.

This behavior exists on many objects. You can typically access many levels of object data that are contained in a single variable. The ability to access this data makes the Exchange Management Shell very flexible.

Return to top

Shell variables are a set of variables that are created and declared automatically by the Exchange Management Shell. The variables are maintained throughout your session as part of the system state and are available to all commands, scripts, and applications that run in that session.

The Exchange Management Shell supports two types of shell variables:

  • Automatic variables provide a mechanism for passing information to and from commands, scripts, and applications.

  • Policy variables store information about the state of the Exchange Management Shell.

You can use shell variables as you would use any other type of variable. For example, the $PSHome shell variable stores the name of the directory where the Exchange Management Shell is installed, and the $_ shell variable stores the current pipeline object. You can use these variables in a command to specify the location of the file and to call a property of the Get-ChildItem object, as shown in the following example:

Get-ChildItem $PSHome | Sort {$_.Name}

This command retrieves all items from the Exchange Management Shell installation directory, and it uses the name property of the object that is stored in the $_ variable to sort the data when it is displayed.

Table 18 lists several common automatic variables that are available for your use in the Exchange Management Shell.

Table 18   Common automatic variables

Automatic variable Description

$$

This variable contains the last token of the last line that is received by the Exchange Management Shell.

$?

This variable contains the success or fail status of the last operation.

$^

This variable contains the first token of the last line that is received by the Exchange Management Shell.

$_

This variable contains the current pipeline object that is used in script blocks, filters, and the Where statement.

$Error

This variable contains objects for which an error occurred when they are processed in a cmdlet.

$ExBin

This variable displays the full path of the Exchange Server\bin directory.

$ExScripts

This variable the full path of the Exchange scripts directory.

$ForEach

This variable refers to the enumerator in a ForEach loop.

$Home

This variable specifies the user’s root directory. It is the equivalent of %HomeDrive%%HomePath%.

$MaximumHistoryCount

This variable specifies the maximum number of entries that can be saved in the command history.

$PSHome

This variable specifies the directory where the Exchange Management Shell is installed.

Return to top

Traditional command shells have always supported the redirection of the output of one command to another in the form of a textual stream. This method has its disadvantages because parsing text has to be carefully controlled, usually by some kind of encoding to prevent unexpected behavior.

Each action that you take in the Exchange Management Shell must be done within the context of objects. The Exchange Management Shell uses structured collections of information that are called objects. These objects represent items in hierarchical data sources. When you call a cmdlet, one or more strongly typed structured objects are returned. Objects carry information about an item and about the object’s structure. The object also acts as a proxy for the real item. For example, when you access a file from the Exchange Management Shell, you work with the object that represents that file, not the file itself.

The Exchange Management Shell uses this object model to pass information from one command to another by using pipelining. This avoids the problems that are caused by textual parsing in other command shells because the data that the Exchange Management Shell uses has a definite structure and is interpreted according to the object model.

An object consists of three types of data: the object’s type, its methods, and its properties.

The data type of an object provides details about what kind of object it is. For example, an object that represents a mailbox is a Mailbox object. An object that represents a file is a FileInfo object. All objects have a distinct predefined type and namespace that the Exchange Management Shell can process.

A method is a set of instructions that define a particular action that you can take on an object. For example, a Mailbox object includes the method Set-EmailAddresses. This can be used to set the value of attribute ProxyAddresses on Active Directory directory service mailbox-enabled user accounts.

A property is data that is associated with an object that specifies a particular state of that object. For example, a Mailbox object includes the property EmailAddresses that was mentioned in "Object Methods" earlier in this section. This object property represents the value of the actual attribute ProxyAddresses on mailbox-enabled Active Directory user accounts. This is the actual item that is represented by the Mailbox object.

The information about properties that is included with an object includes the current state and the definition of each property. This includes its name and the type of data that the property can take, such as Integer, Boolean, String, and so on.

Return to top

An array provides a data structure that can be used to store a collection of data elements of the same type. The Exchange Management Shell supports all kinds of data elements.

For detailed information about how to use arrays, run the following command in the Exchange Management Shell:

Get-Help About_Array

You can create and initialize arrays by assigning multiple values to a variable. The values that are stored in the array are delimited by using a comma and are separated from the variable name by the = assignment operator. For example, suppose you want to create an array that is named $Example that contains the following seven integer values: 22, 5, 10, 8, 12, 9, 80. To create the array, enter the following command:

$Example = 22,5,10,8,12,9,80

In the array, the first data element is at index position 0, the second is at position 1, and so on.

You can reference an array by its variable name, such as $Example. You can reference a specific value within the array by using the index number of the position in the array where the value is stored. For example, to reference the first data element in the $Example array, enter the following command:

Write-Host $Example[0]

The Exchange Management Shell will return the value 22 because that is stored in the first array element.

To change the value of a single item in an array, specify the array name, the index you want to modify, the = assignment operator, and the new value that you want to use instead of the existing value. For example, to change the value of the second item in the $Example array, index position 1, to 10, enter the following command:

$Example[1] = 10

You can also use the SetValue method to change a value. The following example changes the second value, index position 1, of an array named $Example to 500:

$Example.SetValue(500,1)

You can append a value to the end of an existing array. For example, to add an additional integer, such as 200, to the $Example array, enter the following command:

$Example += 200

Associative arrays are the same as regular arrays. However, they enable the assignment of key-value pairs to a variable. For example, you may want to assign values to keys in an array to be called on when a command is being processed. The following example creates an associative array:

$Example = @{blue = 1; red = 2,3}

When you enter $Example on the command line, you see the following output:

Key                            Value
---                            -----
red                            {2, 3}
blue                           1

You can retrieve the information that is stored in the array by calling the array as follows:

$Example.blue 

The previous example returns a value 1.

Because multiple values were assigned to the red key, those values make up a nested array. You can reference the values in this nested array by using their index value. You can retrieve the information that is stored in the key's nested array by calling the associative array, $Example, with the red key and the index of the nested array location that you want to retrieve 1, as follows:

$Example.red[1]

The previous example returns the value 3.

For more information about associative arrays, run the following command in the Exchange Management Shell:

Get-Help About_Associative_Array

Return to top

This section explains how you can use templates in the Exchange Management Shell to copy the configuration of an object to another object.

The examples in this section explain how to use templates when you create a new mailbox by using the New-Mailbox and Set-Mailbox cmdlets. However, you can use templates with many cmdlets. Although the specific requirements for each cmdlet may be different, you use templates in the same manner for all cmdlets.

In Exchange 2007, you can use the Exchange Management Shell to administer objects, such as mailboxes, Send connectors, and e-mail address list policies. These objects can contain many properties that you can configure. Examples of properties that can be configured by an administrator are the properties that determine a conditional custom attribute on an e-mail address list policy, whether a remote domain allows automatic replies to the Internet, and whether DNS routing is enabled on a Send connector.

If you want to create new objects that are based on the configuration of an existing object, you can use templates. When you use a template to create a new object, the Exchange Management Shell can't clone properties that are required and must be unique. Therefore, you must specify the properties that are required and the properties that must be unique when the new object is created.

Let's look at how you can use a template to save time when you want to create 100 mailboxes with the following customized configuration:

 

Property Customized value

RetainDeletedItemsFor

30.00:00:00

ProhibitSendQuota

1GB

ProhibitSendReceiveQuota

1500MB

IssueWarningQuota

750MB

UseDatabaseQuotaDefaults

$False

UseDatabaseRetentionDefaults

$False

The properties in this table are examples of the properties that you can set on mailboxes by using the Exchange Management Shell. When you create a new mailbox by using the New-Mailbox cmdlet, you can't configure these properties. To configure the properties, you must use the Set-Mailbox cmdlet. Without templates, you would have to create each new mailbox and then configure its properties. With templates, you can create one mailbox and configure its properties by using the Set-Mailbox cmdlet. Then you can use the first mailbox as a template and create the rest of the mailboxes by using that template.

noteNote:
You could also use pipelining to pass the new mailbox object from the New-Mailbox cmdlet to the Set-Mailbox cmdlet. The Set-Mailbox cmdlet lets you set the properties of the new mailbox. The advantage of using templates is that you can use an existing object that is configured exactly the way you want to configure new objects. When you use an existing object, you make sure that you maintain a consistent configuration across those objects.
For more information about pipelining, see "Pipelining" earlier in this white paper.

The Exchange Management Shell lets you use templates by supporting the TemplateInstance parameter on many cmdlets that have the verbs New, Add, and Enable. The TemplateInstance parameter accepts an object that is of the same type as the object you are trying to create. For example, if you want to create a new mailbox by using the New-Mailbox cmdlet, you must supply a mailbox object to the TemplateInstance parameter. For more information about cmdlets, see "Understanding Cmdlets" earlier in this white paper. For more information about objects, see "Structured Data" earlier in this white paper.

noteNote:
You may want to create recipients, such as mailboxes or mail-enabled users, that are dedicated to acting as templates. For information about how to secure these dedicated recipient templates, see How to Secure Recipient Templates.

When you run a cmdlet with the TemplateInstance parameter, the cmdlet combines the configuration that is retrieved from the object that is specified in the TemplateInstance parameter with the values that you specified in the required parameters of the cmdlet. The combined configuration is used to create the new object. You can't configure the values on a required parameter by using the TemplateInstance parameter.

noteNote:
If you specify a parameter and its value when you run a cmdlet, the value that you specify with that parameter overrides the value that is configured on the template object.

To use an object as a template, you must first create the object, and then configure its properties. After you've configured the object, you can then create additional objects by using that previously configured object as a template. For example, if you want to create a new mailbox with the configuration that is listed in the table in the earlier section, you first must create the mailbox with the New-Mailbox cmdlet, and then use the Set-Mailbox cmdlet to configure the properties of the mailbox object as in the following example:

$Password = ConvertTo-SecureString Pass@word1 -AsPlainText -Force
New-Mailbox -Name "Kim Akers" -Database "Mailbox Database" -UserPrincipalName kim@contoso.com -Password $Password
Set-Mailbox "Kim Akers" -RetainDeletedItemsFor 30.00:00:00 -ProhibitSendQuota 1GB -ProhibitSendReceiveQuota 1500MB -IssueWarningQuota 750MB -UseDatabaseQuotaDefaults $False -UseDatabaseRetentionDefaults $False

For more information about how to manage mailboxes, see Managing User Mailboxes.

After you have created and configured a mailbox object that you want to use as a template, you can create additional mailbox objects with the same configuration. You must first assign the mailbox object that you want to use as a template to a variable, as in the following example:

$Template = Get-Mailbox "Kim Akers"

It doesn't matter what the variable name is. For more information about variables, see User-Defined Variables.

Now that you have selected a mailbox object to use as a template, you can create a new mailbox by using that template, as in the following example:

$Password = ConvertTo-SecureString Pass@word1 -AsPlainText -Force
New-Mailbox -Name "David Simpson" -Database "Mailbox Database" -UserPrincipalName david@contoso.com -Password $Password -TemplateInstance $Template

After you create the new mailbox, you can use the following command to view the properties of the mailbox object that you configured by using the template to verify they have been set correctly:

Get-Mailbox "David Simpson" | Format-List Name, ProhibitSendQuota, ProhibitSendReceiveQuota, IssueWarningQuota, UseDatabaseQuotaDefaults, UseDatabaseRetentionDefaults, RetainDeletedItemsFor

Name                         : David Simpson
ProhibitSendQuota            : 1GB
ProhibitSendReceiveQuota     : 1500MB
IssueWarningQuota            : 750MB
UseDatabaseQuotaDefaults     : False
UseDatabaseRetentionDefaults : False
RetainDeletedItemsFor        : 30.00:00:00

For more information about the Format-List cmdlet, see "Working with Command Output" earlier in this white paper.

Templates are very useful when you want to create many objects at the same time. For example, you may want to create mailboxes for every user who is listed in a comma-separated value (CSV) file and apply the same configuration to all the new mailboxes. By using the Import-CSV cmdlet and ForEach cmdlet, you can read in the data from the CSV file and then create a mailbox for each user who is listed in the file. For example, assume you want to create new mailboxes for the users in the following CSV file, and apply the mailbox object properties that are configured on the Kim Akers mailbox object. The CSV file, Users.csv, contains the following information:

Name,UPN,MailboxDatabase
Adam Bar,adam@contoso.com,Sales
Mike Ray,mike@contoso.com,Sales
Angela Barbariol,angela@contoso.com,Marketing
Chris Barry,chris@contoso.com,Marketing
Sanjay Jacob,sanjay@contoso.com,Marketing

First, assign the mailbox object that contains the configuration that you want to use with the template, as in the following example:

$Template = Get-Mailbox "Kim Akers"

Then, you can create the mailboxes by using the Import-CSV and ForEach cmdlets:

$Password = ConvertTo-SecureString Pass@word1 -AsPlainText -Force
Import-CSV C:\Users.CSV | ForEach { New-Mailbox -Name $_.Name -UserPrincipalName $_.UPN -Database $_.MailboxDatabase -Password $Password -Template $Template }

For more information about the ForEach cmdlet and how to add multiple recipients, see Using the Exchange Management Shell for Bulk Recipient Management.

Return to top

This topic explains how script security in the Exchange Management Shell helps prevent harmful or otherwise unwanted scripts from running in your organization and what options are available to modify script security to meet the requirements of your organization.

You typically encounter scripts from three different sources: yourself, another person in your organization, and script writers from outside your organization, such as the Internet. If you write a script, you trust the script to do what it is designed to do. If you share the script with other administrators in your organization, they too may trust the script, but only because they trust you.

When scripts come from other sources, such as the Internet, script security is a concern. The only way that you can trust scripts from sources unknown to your organization is to inspect the script code directly and test it in an isolated lab environment. This process can be time-consuming and tedious. But it is a recommended practice to prevent unintentional execution of malicious or destructive code.

The Exchange Management Shell supports the recommended use of digital signatures to make sure a script is not altered after the script is created. For more information about digital signatures, see "Code-Signing Basics" later in this white paper.

Four modes of script execution are possible for the Exchange Management Shell to control how scripts are used, depending on how they are signed and if they are from known or unknown sources. Table 19 describes each script execution mode.

Table 19   Script execution modes

Mode Description

Restricted mode

No scripts will run, even if they are signed by a trusted publisher.

AllSigned mode

All scripts must be digitally signed by a trusted publisher before they will run.

RemoteSigned mode

All scripts that are locally created will run. Scripts that are downloaded from remote locations, such as the Internet, that cannot be trusted, will not run. This is the default script execution mode.

Unrestricted mode

All scripts regardless of whether they are digitally signed or trusted will run. We don't recommend the Unrestricted mode unless you are running the script in a controlled non-production test environment.

To change the script execution mode from the default RemoteSigned script execution mode, locate the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell and change the ExecutionPolicy value to the desired script execution mode. The Exchange Management Shell recognizes the change to the policy immediately.

CautionCaution:
Incorrectly editing the registry can cause serious problems that may require you to reinstall your operating system. Problems resulting from editing the registry incorrectly may not be able to be resolved. Before editing the registry, back up any valuable data.

Large organizations that want to set a consistent script execution mode for all computers that are running the Exchange Management Shell should apply the script execution mode setting by a policy.

Digital signatures are created by using a public-key signature algorithm that uses two different cryptographic keys called a key pair: the public key and the private key. The private key is known only to its owner, and the public key is available to anyone. In digital signatures, the private key generates the signature, and the corresponding public key validates the signature.

A certificate is a digital document that is generally used for authentication and to help secure information on open networks. A certificate securely binds a public key to the entity that holds the corresponding private key. Certificates are digitally signed by the issuing certification authority (CA). By using a code-signing certificate, the author of the script adds a digital signature to the script file. During this process, a one-way hash of the script is created and encrypted by using the private key. The encrypted hash is a digital signature string that is added to the script file. This digital signature string is commented out so that it does not interfere with script functionality.

When this script is run in an Exchange Management Shell environment where code signing is required, a new one-way hash of the script file is produced. The one-way hash is compared to the encrypted hash that is included with the script file after it is decrypted by using the public key. If the script wasn't altered in any way after it was signed, the hashes will match. The computer then tries to verify that the signature is from a trusted publisher by building a certificate chain to a trusted certification authority. If the trust is verified, the script runs.

Whether a script is from a trusted source depends on the origin of the code-signing certificate that was used to digitally sign the script. There are generally two types of certificates:

  • Certificates that are issued by a trusted certification authority   The certification authority verifies the identity of requestor before it issues a code-signing certificate. The issuing authority can be an external, public third party that sells certificates or an internal certification authority that is hosted by your organization. If you sign a script by using this kind of certificate, you can share the script with users on other computers that recognize and trust the certification authority that issued the certificate.

  • Self-signed certificates   For this kind of certificate, your computer is the authority that creates the certificate. The benefit of a self-signed certificate is you can write, sign, and run scripts on your computer. But you can't share your script to run on other computers because they don't recognize your computer as a trusted certification authority. If they don't trust your computer, they can't validate your self-signed signature and the script won't run.

The Exchange Management Shell includes two cmdlets for managing code signing. The Set-AuthenticodeSignature cmdlet is used to add digital signatures to script files. The Set-AuthenticodeSignature cmdlet takes the name of the file to be signed as its first positional parameter. If the file is not in the current working directory, you must provide the path of the file. The second input parameter for this cmdlet is the certificate that is used for signing. This certificate is stored in the local certificate store. You must provide this parameter in the form of a string that references the certificate. The certificate can be accessed through the Cert: drive.

The second cmdlet for managing code signing is the Get-AuthenticodeSignature cmdlet. Use the Get-AuthenticodeSignature cmdlet to check and confirm the current code-signing status for the file that is provided as a parameter input. If a problem occurs when you use a code-signed script, the output from the Get-AuthenticodeSignature cmdlet will provide useful troubleshooting information.

If you want to run scripts from outside sources, such as Microsoft, you must adapt the scripts according to the script execution mode of your environment. You can receive scripts as basic .txt files, rename them as .ps1 script files, and then, after you apply any required signing, run these scripts as if you had written the script yourself.

For more information about digital signing and script execution policies, in the Exchange Management Shell, run the following command: Get-Help About_Signing. This command returns help information that includes detailed instructions for digitally signing scripts.

Return to top

For most general tasks, running cmdlets one at a time or together through pipelines is sufficient. However, sometimes you may want to automate tasks. The Exchange Management Shell supports a very rich scripting language, based on the Microsoft .NET Framework, which resembles the scripting language in other shells. The Exchange Management Shell lets you create scripts, from the very simple to the very complex. Language constructs for looping, conditional, flow-control, and variable assignment are all supported.

Every organization has tasks that are in some way unique to that organization. With a library of script files to perform these tasks, administrators can save time and run these scripts on any computer that has the Exchange Management Shell installed.

For more information about how to use scripts, see Scripting with Windows PowerShell. Because the Exchange Management Shell is built on Windows PowerShell technology, the scripting guidance for Windows PowerShell applies to the Exchange Management Shell.

Those familiar with the Cmd.exe environment know how to run command shell scripts. These are nothing more that text files that have the .bat file name extension. Like batch files, you can create the Exchange Management Shell script files by using a text editor, such as Notepad. The Exchange Management Shell script files use the .ps1 file name extension.

The Exchange Management Shell uses a root directory for script files when they are called. By default, the root directory is the <root drive>:\Program Files\Microsoft\Exchange Server\bin directory. You can also verify the current PSHome directory on any computer that is running the Exchange Management Shell by running $PSHome from the command line. Both of these directories are in the PATH environment variable.

If a script file is saved to the root directory, you can call it by using the script name. If the script file is located somewhere other than the current location, the path and script name must be used. If the script file is located in the current location, the script name must be prefixed by .\.

The following examples show the command syntax requirements for calling three different scripts. These examples all use the Get-Date cmdlet, from three different locations.

[PS] C:\>Get-Date-Script-A.ps1
Friday, January 20, 2006 3:13:01 PM

The script file Get-Date-Script-A.ps1 is located in the directory that is specified by $PSHhome and requires only the script name to run.

[PS] C:\>c:\workingfolder\Get-Date-Script-B.ps1
Friday, January 20, 2006 3:13:25 PM

The script file Get-Date-Script-B.ps1 is located in the C:\workingfolder directory so the full path must be supplied to run.

[PS] C:\>.\Get-Date-Script-C.ps1
Friday, January 20, 2006 3:13:40 PM

The script file Get-Date-Script-C.ps1 is located in the current location, C:\. Therefore, it must be prefixed with .\ to run.

[PS] C:\>Get-Date-Script-C.ps1
'Get-Date-Script-C.ps1' is not recognized as a Cmdlet, function, operable program, or script file.
At line:1 char:21
+ Get-Date-Script-C.ps1 <<<<

In the last example, when this same script, Get-Date-Script-C.ps1, is called without the prefix .\, the expected results are shown.

As a best practice, always give script files a descriptive name and include comments in the script to describe its purpose and to identify each point of interest. Some information about the author should also be included in case someone who is running the script has questions about its use. Use the pound symbol (#) to start comment lines inside the script body.

If you want to run a script on a scheduled basis by the Windows Task Scheduler service, you can call the Exchange Management Shell and include the script that you want to run as a parameter. Because the Exchange Management Shell is a snap-in of the Windows PowerShell, you must also load the Exchange Management Shell snap-in when you run the command in order to run any Exchange -related cmdlets. The following syntax is required to load the Exchange Management Shell snap-in and run your script from the Cmd.exe command:

PowerShell.exe -PSConsoleFile "C:\Program Files\Microsoft\Exchange Server\Bin\ExShell.Mcf1" -Command ". '<Path to Your Script>'"

For example, to run the script RetrieveMailboxes.ps1 from C:\My Scripts, use the following command:

PowerShell.exe -PSConsoleFile "C:\Program Files\Microsoft\Exchange Server\Bin\ExShell.Mcf1" -Command ". 'C:\My Scripts\RetrieveMailboxes.ps1'"

For additional options to use when you call the Exchange Management Shell from the Cmd.exe environment, type PowerShell.exe /?

In Exchange 2007, you can use the Exchange Management Console to view detailed information about specific Exchange Management Shell commands that are used to perform certain tasks. When you run a wizard in the Exchange Management Console, the wizard takes the information that you entered and creates an Exchange Management Shell command that is then run by the computer. You can copy and paste this command directly into the Exchange Management Shell or copy it into a text editor where you can modify it. If you examine how the Exchange Management Console creates commands, you can obtain a better understanding of how to construct or modify those commands to suit your future needs.

For example, if you create a new mailbox for a person named Frank Lee, the following information is displayed on the Completion page of the New Mailbox wizard shown in Figure 2:

Figure 2   New Mailbox wizard completion page

New Mailbox Completion Page

The information that is displayed on the Completion page gives you an idea of the information that you must have to make sure a similar command that you run in the Exchange Management Shell is completed successfully. On the Completion page, press CTRL+C to copy this information to the Clipboard. Then you can use a text editor to examine the command to determine what must be changed to add more mailboxes. You can also customize the command so that it can be used as part of a script that consumes a comma-separated-values (CSV) file or another input source to automate creating many mailboxes.

When you create new scripts, you should always test them in a lab environment before you apply them in your production environment. As you test your scripts in your lab, and as you deploy them in your production environment, you can use the WhatIf parameter that is available on many cmdlets included in the Exchange Management Shell to verify that your script performs as expected. The WhatIf parameter instructs the command to which it is applied to run, but only to display which objects would be affected by running the command and what changes would be made to those objects, without actually changing any of those objects.

For more information about the WhatIf parameter, see "WhatIf and Confirm" earlier in this white paper.

Scripts may not work as expected for many reasons. It can be difficult to determine where the problem is and what is going wrong. The Exchange Management Shell can help you locate general syntax errors by reporting the line and character at the point of failure. When the syntax of a script is correct but its behavior is unexpected, it can be much more difficult to diagnose the problem. The Exchange Management Shell includes simple debugging functionality to troubleshoot script files by examining each step that the script makes as it executes. This functionality is called tracing.

To enable tracing and examine each command step in a script, use the Set-PSDebug cmdlet with the Trace parameter set to a value of 1. To examine each step and each variable assignment as they are made, set the Trace parameter to a value of 2. To turn off tracing, set the value of the Trace parameter to 0 (zero).

To examine each command in a script line by line, use the Set-PSDebug cmdlet with the Step parameter. At each step, you will be prompted to continue the operation. The following choices are available in Step mode:

[Y] Yes (continue to the next step)
[A] Yes to All (continue to the end of the script)
[N] No (stop this step)
[L] No to All (stop all remaining steps)
[S] Suspend (suspend at this point and drop to a prompt)

Suspend lets you exit to a prompt where you can run any command, for example, to check or set values on an object before the script can access it. When you are ready to resume script execution, type Exit and control immediately returns to the point at which the script was suspended.

Return to top

This section provides sample output from Exchange Management Shell commands that you would typically run on a computer that is running Exchange 2007. Each example provides the default display of information and the optional verbose display of information.

This section is not intended to show how to configure the components or features that are highlighted in the following examples. Each example is preceded by a link to the procedural topic that is associated with the component or feature.

For more information about how to manage Simple Mail Transfer Protocol (SMTP) connectors, see the "Managing SMTP Connectors" topic in Exchange Server 2007 Help.

The Get-ReceiveConnector "Client MBX" command retrieves the following default display of information:

Name                      Bindings                   Enabled
----                      --------                   -------
Client MBX                {0.0.0.0:587}              True 

The Get-ReceiveConnector "Client MBX" | Format-List command retrieves the following verbose display of information:

Schema                                  : Microsoft.Exchange.Data.Directory.SystemConfiguration.ReceiveConnectorSchema
AuthMechanism                           : Tls, BasicAuth, BasicAuthPlusTls, ExchangeServer
Banner                                  :
BinaryMimeEnabled                       : True
Bindings                                : {0.0.0.0:587}
ChunkingEnabled                         : True
DefaultDomain                           :
DeliveryStatusNotificationEnabled       : True
EightBitMimeEnabled                     : True
EnhancedStatusCodesEnabled              : True
ExternallySecuredAsPartnerDomain        :
Fqdn                                    : MBX.contoso.com
Comment                                 :
Enabled                                 : True
ConnectionTimeout                       : 00:10:00
ConnectionInactivityTimeout             : 00:05:00
MessageRateLimit                        : 600
MaxInboundConnection                    : 5000
MaxInboundConnectionPerSource           : 100
MaxInboundConnectionPercentagePerSource : 2
MaxHeaderSize                           : 64KB
MaxHopCount                             : 30
MaxLocalHopCount                        : 3
MaxLogonFailures                        : 3
MaxMessageSize                          : 10MB
MaxProtocolErrors                       : 5
MaxRecipientsPerMessage                 : 200
PermissionGroups                        : ExchangeUsers
PipeliningEnabled                       : True
ProtocolLoggingLevel                    : None
RemoteIPRanges                          : {0.0.0.0-255.255.255.255}
RequireEHLODomain                       : False
RequireTLS                              : False
Server                                  : MBX
SizeEnabled                             : True
TarpitInterval                          : 00:00:05
AdminDisplayName                        :
ObjectCategoryName                      : msExchSmtpReceiveConnector
ExchangeVersion                         : 0.1 (8.0.535.0)
CurrentObjectVersion                    : 0.1 (8.0.535.0)
Name                                    : Client MBX
DistinguishedName                       : CN=Client MBX,CN=SMTP Receive Connectors,CN=Protocols,CN=MBX,CN=Servers,CN=Exchange Administrative Group (FYDIBOHF23SPDLT),CN=Administrative Groups,CN=First Organization,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=contoso,DC=com
Identity                                : MBX\Client MBX
Guid                                    : ee9828f3-c88c-4ea9-9797-b76926a0019e
ObjectCategory                          : contoso.com/Configuration/Schema/ms-Exch-Smtp-Receive-Connector
ObjectClass                             : {top, msExchSmtpReceiveConnector}
OriginalId                              : MBX\Client MBX
WhenChanged                             : 6/19/2006 5:19:39 PM
WhenCreated                             : 6/19/2006 5:19:39 PM
ObjectState                             : Unchanged
OriginatingServer                       : MBX.contoso.com
IsReadOnly                              : False
Id                                      : MBX\Client MBX
IsValid                                 : True 

For more information about how to manage administrator commands, see the "Mailbox Server Cmdlets" topic in Exchange Server 2007 Help.

The Get-Mailbox command retrieves the following default display of information:

Name                      Alias                Server           ProhibitSendQuota
----                      -----                ------           ---------------
Administrator             Administrator        dc1              unlimited
Kim Akers                 KimAkers            dc1              unlimited

The Get-Mailbox "Administrator" | Format-List command retrieves the following verbose display of information:

Id                                 : contoso.com/Users/Administrator
IsValid                            : True
Item                               :
DistinguishedName                  : CN=Administrator,CN=Users,DC=contoso,DC=com
Guid                               : 104f5066-9d9c-4596-907b-88e5270d79b3
Identity                           : contoso.com/Users/Administrator
Name                               : Administrator
ObjectCategory                     : contoso.com/Configuration/Schema/Person
ObjectCategoryName                 : user
ObjectClass                        : {top, person, organizationalPerson, user}
ObjectState                        : Unchanged
OriginatingServer                  : DC1.contoso.com
Schema                             : Microsoft.Exchange.Data.Directory.Manageme
                                     nt.MailboxSchema
WhenChanged                        : 7/11/2006 8:15:13 PM
WhenCreated                        : 6/29/2005 4:39:20 PM
SamAccountName                     : Administrator
Database                           : DC1\First Storage Group\Mailbox Database
RetentionHoldEnabled               : False
EndDateForRetentionHold            :
StartDateForRetentionHold          :
ManagedFolderMailboxPolicy         :
ServerLegacyDN                     : /o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Configuration/cn=Servers/cn=DC1
ServerName                         : dc1
UseDatabaseQuotaDefaults           : True
StorageQuota                       :
RulesQuota                         : 64KB
DeletedItemFlags                   : DatabaseDefault
UseDatabaseRetentionDefaults       : True
RetainDeletedItemsUntilBackup      : False
DeliverToMailboxAndForward         : False
ExchangeGuid                       : 75086963-d1bc-446c-9f4b-5a04385e3d80
ExchangeSecurityDescriptor         : System.Security.AccessControl.RawSecurityDescriptor
ExchangeUserAccountControl         : None
ExternalOofOptions                 : External
RetainDeletedItemsFor              : 14.00:00:00
IsMailboxEnabled                   : True
OfflineAddressBook                 :
ProhibitSendQuota                  : unlimited
ProhibitSendReceiveQuota           : unlimited
UserPrincipalName                  :
Office                             :
AcceptMessagesOnlyFrom             : {}
AcceptMessagesOnlyFromDLMembers    : {}
AddressListMembership              : {Default Global Address List, All Users}
Alias                              : Administrator
AntispamBypassEnabled              : False
CustomAttribute1                   :
CustomAttribute2                   :
CustomAttribute3                   :
CustomAttribute4                   :
CustomAttribute5                   :
CustomAttribute6                   :
CustomAttribute7                   :
CustomAttribute8                   :
CustomAttribute9                   :
CustomAttribute10                  :
CustomAttribute11                  :
CustomAttribute12                  :
CustomAttribute13                  :
CustomAttribute14                  :
CustomAttribute15                  :
DisplayName                        : Administrator
EmailAddresses                     : {SMTP:Administrator@contoso.com, X400:c=US;a= ;p=First Organizati;o=Exchange;s=Administrator;}
ForwardingAddress                  :
GrantSendOnBehalfTo                : {}
HiddenFromAddressListsEnabled      : False
LegacyExchangeDN                   : /o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=Administrator
MasterAccountSid                   :
MaxSendSize                        : unlimited
MaxReceiveSize                     : unlimited
PoliciesIncluded                   : {{43C0F25A-8B8F-410E-9296-D5DCF590CE7C},{26491CFC-9E50-4857-861B-0CB8DF22B5D7}}
PoliciesExcluded                   : {}
EmailAddressPolicyEnabled          : True
PrimarySmtpAddress                 : Administrator@contoso.com
ProtocolSettings                   : {}
RecipientLimits                    : unlimited
RecipientType                      : MailboxUser
RecipientTypeDetails               : MailboxUser
RejectMessagesFrom                 : {}
RejectMessagesFromDLMembers        : {}
RequireSenderAuthenticationEnabled : False
ResourceType                       :
ResourceCapacity                   :
ResourceCustom                     : {}
IsResource                         : False
IsShared                           : False
IsLinked                           : False
SCLDeleteThreshold                 :
SCLDeleteEnabled                   :
SCLRejectThreshold                 :
SCLRejectEnabled                   :
SCLQuarantineThreshold             :
SCLQuarantineEnabled               :
SCLJunkThreshold                   :
SCLJunkEnabled                     :
SimpleDisplayName                  :
WindowsEmailAddress                : Administrator@contoso.com
Languages                          : {}

Return to top

One of the Exchange Management Shell Tips of the Day is displayed every time that you open the Exchange Management Shell.

To view a tip of the day on-demand, open the Exchange Management Shell and run the Get-Tip cmdlet.

To view the list of tips, along with links to related topics, see Exchange Management Shell Tips of the Day.

The Exchange Management Shell provides you with an administration interface that is intuitive and easy to use, while at the same time powerful and flexible. Whether you administer a single Exchange server or are responsible for a global Exchange infrastructure, the Exchange Management Shell will help you take control of Exchange 2007 and push it to its fullest potential.

  • For a list of frequently used Exchange Management Shell command examples that are organized by administrative functions, such as recipient management and transport configuration, see Exchange Management Shell Quick Reference.

  • For information about individual Exchange Management Shell cmdlets, see Exchange Management Shell.

  • For a list of all cmdlets arranged by noun, see Cmdlet List.

  • For more information about how to use the Exchange Management Shell cmdlets to manage your Exchange 2007 organization, see the Operations section in Exchange Server 2007 Help.

Return to top

 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft