How to test Exchange Management Shell commands

There's often confusion about whether the Exchange Management Shell (EMS) is the same as Windows Power Shell. This a valid mistake because the EMS builds on top of Windows Power Shell. If you open Windows Power Shell and try to enter an Exchange Server-related command, this won't work because Windows Power Shell is not Exchange-aware by default. However, the Exchange Management Shell provides a set of extended commands to the Windows Power Shell so that administrators can interact with Exchange Server from a command prompt.

The WhatIf parameter

The WhatIf command lets you see a command's actions, without having to perform the command. This prevents administrators from entering the wrong command accidentally.

For example, if you enter the Enable-AntiSpamUpdates command, Exchange will enable antispam mechanisms to be updated. However, if you were concerned about whether the command would enable antispam updates on the current Exchange server only or for the entire organization, you must append the –WhatIf parameter to the command. The command would look like this:

Enable-AntiSpamUpdates –WhatIf

After entering the command, you would receive a line of output text (Figure 9) similar to the following:

What if: Enabling Anti-Spam Updates on "server1.contoso.com"

Figure 9. The WhatIf parameter shows how a command will behave. (Click on image for enlarged view.)

When you append the WhatIf parameter to a command, the Exchange Management Shell won't display operation results, but will show what the operation looks like in action. In this example, we don't receive confirmation that antispam updates were enabled, but we see what the command would look like while enabling those updates. Additionally, the output begins with What if:, which shows that the command hasn't been executed.

The WhatIf parameter cannot be used with every Exchange Management Shell command. For instance, if you try to use the –WhatIf parameter in conjunction with the Get-Mailbox command, you'll receive an error message explaining that a parameter cannot be found that matches the 'WhatIf' parameter. Fortunately, there is an easy way to know whether or not you can use this parameter. Open the Exchange Management Shell and enter:

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

The Exchange Management Console will display every command that works with the WhatIf parameter (Figure 10).

Figure 10. The Exchange Management Shell displays the commands that work with the WhatIf parameter. (Click on image for enlarged view.)

The ValidateOnly parameter

The Exchange Management Shell allows administrators to perform involved actions by entering a single command. However, this can be problematic if you don't know what you're doing. This is where the ValidateOnly parameter can come into play.

The ValidateOnly parameter has two general purposes.

• It allows you to see how a command will behave before you attempt to run the command.
• The parameter helps to ensure that all of a command's dependencies are in place before you execute a command.

The ValidateOnly parameter is suitable in situations in which you're using a complex string of commands that are piped together or one in which the command will take a long time to complete. For example, imagine a situation in which a mailbox store has become too large, so you want to move a subset of users to a different mailbox store.

In this case, the command used to perform the move may or may not be complex, depending on the nature of the move. It fits other criteria as well. If you are moving several mailboxes, then the move will probably take a long time to complete. Making a mistake in this command could wreak havoc on your Exchange organization. A mistake like moving the wrong mailboxes could take several days to complete and would be very disruptive to users.

The stakes are high when moving mailboxes via the Exchange Management Shell. Fortunately, you can use the ValidateOnly parameter to validate the entire process before performing the move. For instance, if I wanted to move a single user named User3 to a mailbox store named Users. The Users store is located on the same server as the store that now holds the mailbox. In this case, you could use the following command to perform the move:

Get-Mailbox "User3" | Move-Mailbox –TargetDatabase "Users"

That command works, but it's best to run the command by appending the –ValidateOnly parameter to the end of it. The command should look like:

Get-Mailbox "User3" | Move-Mailbox –TargetDatabase "Users" –ValidateOnly

Exchange Server will display output similar to that in Figure 11. This screen shows that the command's output differs considerably from the output that the WhatIf parameter generates.

Figure 11. The ValidateOnly parameter lets you view results that a command will generate when executed. (Click on image for enlarged view.)

The WhatIf parameter shows you what action the command will perform. In contrast, the ValidateOnly parameter to displays the results that the command would have generated had you run it. Like the WhatIf parameter, the ValidateOnly parameter is limited for use with certain commands. To display a list of the commands that are compatible with the ValidateOnly parameter, enter:

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

In this command line, as well as all commands that are compatible with the ValidateOnly parameter, the phrase ValidateOnly is surrounded by asterisks (*). This informs the command that any additional text before or after the words ValidateOnly are acceptable.

More Exchange Management Shell resources: Manage Exchange 2007 public folders with the Exchange Management Shell How to create Exchange 2007 journaling rules with Exchange Management Shell

This same principle of using wildcards can also be applied to the Get-Help command. Although EMS commands are comprised of verb-noun combinations, most commandlets (nouns) don't work with every possible verb. You can use the Get-Help command, combined with a wildcard, to determine which verbs work with a particular commandlet.

For example, in the Get-Mailbox command, Get is the verb, and –Mailbox is the commandlet. To determine which other verbs work with the –Mailbox commandlet, enter the following command:

Get-Help *-Mailbox

Results of this command are shown in Figure 12. Microsoft offers more Get-Help command resources and troubleshooting tips on its website.

Figure 12. The Get-Help *-Mailbox command lists all commands related to the Mailbox commandlet. (Click on image for enlarged view.)

A PRIMER ON THE EXCHANGE 2007 EXCHANGE MANAGEMENT SHELL

 Home: Introduction
 Part 1: How to use the Exchange Management Shell command syntax
 Part 2: How to use the Exchange Management Shell Filter command
 Part 3: Control query results with the EMS Format command
 Part 4: How to test Exchange Management Shell commands

ABOUT THE AUTHOR:

Brien M. Posey, MCSE Brien M. Posey, MCSE, has previously received Microsoft's MVP award for Exchange Server, Windows Server and Internet Information Server (IIS). Brien has served as CIO for a nationwide chain of hospitals and was once responsible for the Department of Information Management at Fort Knox. As a freelance technical writer, Brien has written for Microsoft, TechTarget, CNET, ZDNet, MSD2D, Relevant Technologies and other technology companies. You can visit Brien's personal Web site at http://www.brienposey.com.