A Primer on the Exchange Management Shell

By David Strome

New in Microsoft Exchange Server 2007 is the Exchange Management Shell, a powerful management interface, built on Microsoft Windows PowerShell technology. You can use the Exchange Management Shell to perform every task available in the Exchange Management Console and tasks that you can't perform in the Exchange Management Console. What's more, when you perform a task in the Exchange Management Console, the same command is made available to the Exchange Management Shell and called to process the request.

Figure 1 shows the Exchange Management Shell in action.

Figure 1   The Exchange Management Shell

At first glance, the shell may look daunting to those unfamiliar with the command line. But let's take a look at the cool stuff you can do and how easy it is to get started:

• Scripting made safe and easy   The Exchange Management Console doesn’t simply use the Exchange Management Shell to perform operations. The wizards show you the Exchange Management Shell commands they're performing. You can copy the commands that the wizards create and paste them directly onto the command line or into a script. After you've modified the parameters to your liking, test your scripts or commands by using the WhatIf parameter, which lets you see the results before you make any changes to your environment.

  Modify parameters? WhatIf? Sounds complicated? Not to worry! Check out the "Using the Exchange Management Shell" section in the Microsoft Exchange Server 2007 documentation. You'll be up and running in no time.

• Clear and simple   We've used consistent verb-noun pairs to clearly identify the feature or component being managed, and the action that's being taken. You don't have to guess what a cmdlet does anymore. When you see the Move-Mailbox cmdlet, you know exactly what it’s used for. (Yep, that's right. You use it to move mailboxes!)

• Maximize your resources and time, not your frustration   The Exchange Management Shell gives you a robust and flexible scripting platform to integrate with your current scripting solutions, and it lets you communicate natively with data sources like COM and Windows Management Instrumentation (WMI). Use your resources and time wisely to create useful solutions instead of creating the framework to support them.

• Repeat after me: No more text parsing!   Based on Microsoft .NET, the Exchange Management Shell cmdlets accept and return structured data instead of plain text. In this way, you can easily pass data back and forth without messy text parsing. You can even turn CSV and XML files into objects that you can manipulate and consume in a single line.

A Few Basic Concepts

Before you get started with the Exchange Management Shell, it's helpful to understand a few basic concepts.

• The underlying Windows PowerShell technology   The Windows PowerShell is a new, powerful, and extremely flexible command line interface that’s based on the .NET Framework. It combines the best of several shells, plus some great new features. PowerShell is designed to host other applications, just as the Microsoft Management Console (MMC) acts as a host for the various snap-ins that are provided with applications that are installed on a computer. The Exchange Management Shell is the first Microsoft PowerShell snap-in to be released.

• Cmdlets   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. Unlike in other shells, in the Exchange Management Shell, cmdlets have descriptive verb-noun names. The verb describes the action the cmdlet takes, and the noun describes the component or feature that is acted upon. For example, you use the New-SystemMessage cmdlet to create new delivery status notification (DSN) or quota messages on computers that have the Hub Transport server role installed.

  For more information about specific cmdlets, see the "Exchange Management Shell" section in Exchange 2007 Help's Technical Reference node.

• Identity and positional 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. You can use the Identity parameter with most Exchange 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 object using the unique value that makes most sense to you.

  The Identity parameter is a collection of values from other parameters. These values are guaranteed to be unique across that set of objects. You can specify the values of these other parameters, such as Name and DistinguishedName, or the values can be system-generated, such as a GUID. 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. 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. Because Identity is a positional parameter that resides in position 1, which is the first position, any value entered in this position without a parameter name is considered to be an Identity parameter value.

  And what does this mean? Well, it reduces the number of keystrokes when you type commands. For example, Get-Mailbox "Kim Akers" performs the same action as Get-Mailbox -Identity "Kim Akers".

• Pipelining    In the Exchange Management Shell, pipelining refers to the act of one cmdlet using the output of another cmdlet when it performs an operation. You can use pipelining to string together two or more cmdlets. That means you can 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, as in the following example which moves all the mailboxes in the Sales database to the Research database on the same server:

  Get-MailboxDatabase Sales | Get-Mailbox | Move-Mailbox -TargetDatabase Research
  

  See how the pipe "|" symbol is used? First, the Sales mailbox database is retrieved by using the Get-MailboxDatabase cmdlet and the resulting object is piped to the Get-Mailbox cmdlet. Then, all the mailboxes in the Sales database are retrieved by the Get-Mailbox cmdlet. The resulting set of mailboxes is then piped to the Move-Mailbox cmdlet, which moves the mailboxes to the Research mailbox database. This command is shown in Figure 1 earlier in this article.

  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. "Noun cmdlet set"? What's that? All Exchange Management Shell cmdlets that manage a particular feature share the same noun, such as Mailbox or AddressList. For a list of all cmdlets arranged by noun, see Cmdlet List.

Starting the Exchange Management Shell

Windows PowerShell snap-ins are collections of cmdlets used to administer an application or major component. If you don’t load the snap-in for the specific application, you can’t use its associated cmdlets.

What does that mean to you? If you start PowerShell without loading the Exchange Management Shell snap-in, and try to issue an Exchange Management Shell cmdlet, such as Get-Mailbox, you’ll get an error. Why? Because the Get-Mailbox cmdlet doesn’t exist in the core set of PowerShell cmdlets.

So first things first: Let's open the Exchange Management Shell. Simply click Start, click Programs, Microsoft Exchange Server 2007, and then Exchange Management Shell.

For more background information to get you started, see New Administration Functionality in the Exchange Management Shell.

Getting Help Where and When You Need It

For Exchange 2007, the Microsoft Exchange User Education team has developed a robust set of documentation, available inside the Exchange Management Shell and in the Exchange Server 2007 Help file that is available in the Exchange Management Console and online.

In the shell, you'll find that the Get-Help cmdlet is an invaluable resource as you learn to navigate the Exchange Management Shell. And be sure to check out the Operations section in the Exchange Server 2007 Help file. It includes dozens of procedural topics that will help you perform most administrative tasks by using the Exchange Management Shell and the Exchange Management Console. You can access the Exchange Server 2007 Help file from the Start menu of Exchange 2007 and online at Microsoft Exchange Server 2007.

Help in the Shell

In the shell itself, use the Get-Help cmdlet to access cmdlet-specific help in a variety of formats. Typing Get-Help by itself displays general help information. And the Get-Help cmdlet is even more powerful when you start supplying parameters.

To get help for a specific cmdlet, type Get-Help followed by the cmdlet you want information about, such as Get-Help Get-SystemMessage. By default, the shell displays a description of the cmdlet and its syntax. It suppresses other sections that may not be used by all administrators.

You can control what information is presented to you by using the Detailed, Full, and Example parameters. Just add them to the end of the command. For example, Get-Help –Full returns all the help sections available for a cmdlet. Try the commands out for yourself to see what information is displayed for your favorite cmdlets.

If you want to retrieve information about a specific parameter or parameters on a cmdlet, you can use the Parameters parameter with the Get-Help cmdlet. For example, if you want to view all the parameters and their descriptions on the Set-Mailbox cmdlet that contain the word “quota”, type Get-Help Set-Mailbox –Parameter *quota*.

Or maybe you 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. You can do this by using the Get-Help cmdlet and three parameters: Role, Component, and Functionality. When you use the Get-Help cmdlet with these parameters, remember to 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 “Getting Help” topic in the Exchange Server 2007 Help file lists all the role, component, and functionality values that can be used.

Formatting Command Output

By default, when command output is displayed to the screen, the Exchange Management Shell displays only a subset of the available properties for each object. Why? Because each object can contain dozens of properties, and you'll want to optimize the command output for your needs. You can easily access and view all these properties by piping the output of a command to the following three formatting cmdlets: Format-List, Format-Table, and Format-Wide.

Format-List and Format-Table are most frequently used so let's look at them more closely.

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, which is a positional parameter. If you call the Format-List cmdlet 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, as in this example, Get-DistributionGroup | Format-List Name, *OnlyFrom, PrimarySmtpAddress, *Size*. Figure 2 shows the output of this command.

Figure 2   Format-List example output

The Format-Table cmdlet lets you display items in a table format with labeled headers and columns of property data. By default, many cmdlets, such as the Get-Mailbox and Get-JournalRule cmdlets, use the table format for output. Among the parameters for the Format-Table cmdlet are the Properties and GroupBy parameters. These work exactly as they do with the Format-List cmdlet. To display long lines of property information completely instead of truncating at the end of a line, use the Wrap parameter with the Format-Table cmdlet, as in the following example: Get-Mailbox -Database Research | Format-Table Name, ProhibitSendQuota, Database -Wrap. Figure 3 shows the output of this command.

Figure 3   Format-Table example output

You can also specify a wildcard character "*" with a partial property name with both the Format-List and Format-Table Cmdlets, as I showed in Figure 2. 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. Less typing and more time to play with Exchange 2007!

For More Information

To learn more about Exchange 2007 and the Exchange Management Shell, see the following resources:

• Microsoft Exchange Server 2007: In-depth product documentation

• Using the Exchange Management Shell: Information to get you up and running with the shell

• Exchange Management Shell Quick Reference: A downloadable list of frequently used cmdlets that are organized by administrative functions, such as recipient management and transport configuration

• The Microsoft Exchange Team Blog: A blog maintained by the Exchange product team. It's a great source for Exchange and industry news, in-depth product discussion, tips and tricks, and other information.

• Scripting with Windows PowerShell: Script Center: Resources for system administrators who are interested in learning about the Windows PowerShell command line and scripting environment

David Strome - Technical Writer, Microsoft Exchange Server

-