Setting Up Exchange Management Shell

Executive Summary:

In previous articles, I've discussed how Exchange Management Shell lets you use scripts to automate Exchange Server 2007 management ("Windows PowerShell Transforms Exchange Server 2007 Management," April 17, 2007, InstantDoc ID 95295, and "Using the Shell to Manage Exchange 2007," June 5, 2007, InstantDoc ID 95843) . Now it's time to consider aspects such as customizing Exchange Management Shell and the importance of scoping to process the right data.

Personal PowerShell
When you install Exchange 2007 on a server (or the management components on a Windows XP workstation), Exchange Management Shell is placed on the Windows Start menu. Starting the management shell calls a PowerShell script, Exchange.ps1, from the Exchange binaries directory. Exchange.ps1 uses the Add-PSSnapin cmdlet to instruct PowerShell to load the Exchange snap-in, which contains the commands specific to Exchange objects such as mailboxes, servers, and public folders. After loading the snap-in, the commands in Exchange.ps1 define variables used by the shell. For example, the $ExBin variable points to the Exchange binaries directory and $ExScripts points to the Exchange scripts directory. The $AdminSessionADSettings variable is also defined—I'll return to its use shortly. These are all global variables: You can use them anywhere during your PowerShell session.

After everything is initialized, PowerShell presents you with a command window for working with Exchange. As Figure 1 shows, you can customize the font, layout, and colors that Exchange Management Shell uses in its command window by using the shell's properties sheet. For example, you might decide to use a larger or more readable font.

In addition to the variables defined by Exchange.ps1, you can define other variables in your personal PowerShell profile. Windows doesn't create your profile automatically; you'll have to create a file called Microsoft.PowerShell_profile.ps1 with an editor such as Notepad and save it to My DocumentsWindowsPowerShell. (For a discussion about the use of PowerShell profiles, see http://www.leeholmes.com/blog/TheStoryBehindTheNamingAndLocationOfPowerShellProfiles.aspx.) You can define whatever variables you need and insert other commands to personalize your working environment. After you've created the profile, you can edit it from within Exchange Management Shell by using the command

Invoke-Item $Profile 

You have to restart the shell for changes in your profile to be effective. Figure 2 shows a sample profile, and Figure 3 shows how the shell displays that profile. You can scan the Internet to discover the many different customizations people have applied through their personal profiles, such as defining new aliases as command shortcuts and creating a different prompt. Note that PowerShell executes your profile first, then executes the commands in Exchange.ps1. It's important that you don’t attempt to create a variable in your profile that will then be overwritten by Exchange.ps1.

Scoping
The $AdminSessionADSettings global variable set by Exchange.ps1 controls the scope of Active Directory (AD) lookups during an Exchange Management Shell session. By default, the scope for queries performed against AD is the domain of the server or workstation on which you run the shell. If you have a multidomain forest, any query you perform still returns objects only from the local domain.

For example, let's assume you have a forest implementation where a root domain has three child domains to support accounts called South, West, and East. You have Exchange servers installed in each regional domain, and you use Custom Attribute 15 to identify which region mailboxes belong to. If you execute the command

Get-Mailbox -Filter ` {CustomAttribute15 -eq "West"} | ` Select Name 

you might expect to search the entire forest to return a list of mailboxes that belong to the West region. However, you'll find only the mailboxes in the local domain that have “West” set in Custom Attribute 15 because the default scope for AD lookups doesn't extend beyond the local domain. The potential for confusion is obvious.

When Exchange Management Shell initializes, the scope is set with the ViewEntireForest property of the $AdminSessionADSettings global variable. You can edit the ViewEntireForest property to set the scope to view the entire forest as follows:

AdminSessionADSettings.ViewEntireForest = $True 

To reset the scope so that the shell uses objects from only the local domain, type

$AdminSessionADSettings.ViewEntireForest = $False 

You can make the change interactively through the shell or by adding the code to your profile. The first option is best if you need to make a one-time change; use the profile option if you usually work in multidomain mode.

Clearly, creating the proper scope for AD lookups is critical for such things as retrieving the correct set of mailbox data. Incorrect scoping can catch you out in many ways. For example, the Update-SafeList cmdlet gathers safe list information from user accounts and aggregates them so that Exchange can synchronize the data to an Edge Transport server. Antispam agents running on the Edge server can then use the aggregated user safe list data to avoid false positives. If you execute the Update-SafeList cmdlet with the wrong scope, you'll aggregate only the safe list data from the in-scope domain and therefore provide the Edge server with incomplete data.

If you don't want to set your scope to the entire forest, a workaround is to specify a Global Catalog (GC) server in the remote domain to use for the query. For example, if we include a GC in the South domain, we can check whether any West mailboxes exist in that domain with the following command:

Get-Mailbox -DomainController ` GC01.South.MyOrg.Com ` -Filter {CustomAttribute15 ` -eq "West"} | Select Name 

Changing the scope for AD queries will affect how you work with Exchange Management Shell. When you set a forestwide scope, you might have to wait longer for a response from any command, but in most cases the wait is worthwhile because you see the big picture and don't run the risk of missing something. To save time, you need to use parameters to focus on particular groups of objects, such as specifying that you want to work with the mailboxes from a specific server.

Of course, when you set a forestwide scope, it's important to be efficient with your queries, and that's where filters come to your assistance. I'll talk about filters as well as batch execution in my next article in this series on PowerShell for Exchange administrators.