Exchange Management Shell in Exchange 2010
Topic Last Modified: 2009-04-29
By David Strome
The Exchange Management Shell is a powerful command-line management interface, built on Windows PowerShell v2, which enables you to administer every part of Microsoft Exchange Server 2010. You can be an administrator who needs to perform day-to-day management of your mailboxes, or you can be a developer who needs to automate administration using a custom line of business application. Either way, the Shell enables you to do more, faster.
The Shell lies at the heart of the administration model in Exchange 2010. Both the Exchange Management Console (EMC) and the Exchange 2010 web interface use the Shell to process actions. When you view a mailbox, create a distribution group, or mount a database, the EMC and the web interface run a Shell command that performs the actual request. You can do everything in the Shell that can be done in the EMC or the web interface, and more. Later on in this article I'll talk more about how you can use this versatility to your advantage and learn more about the Shell.
This article talks about the following:
A Few Basic Concepts
Role Based Access Control
Starting the Shell
Getting Help Where and When You Need It
Exposing Shell Commands in the Console
Formatting Command Output
First, let's get some basic concepts about the Shell out of the way.
The underlying Windows PowerShell technology Windows PowerShell v2 is a powerful and extremely flexible command-line interface that’s based on the Microsoft .NET Framework. It combines the best of several shells, plus some great new features.
Along with Windows PowerShell, Exchange 2010 uses Windows Remote Management (WinRM) 2.0. The Shell always connects to an Exchange 2010 server via an Internet Information Server (IIS) virtual directory, regardless of whether you're connecting to a local server or a server across the country. WinRM is the communication mechanism between your Shell session and the Exchange 2010 server.
Cmdlets A cmdlet, pronounced "command-let", is the smallest unit of functionality in the Exchange Management Shell. Cmdlets, which have descriptive verb-noun names, resemble built-in commands in other shells, for example, the Dir command found in cmd.exe. Cmdlets manage objects, which are the collection of properties that represent all the different pieces of Exchange. There are server objects, mailbox objects, transport rule objects, and so on. Every instance of something, such as a mailbox, is represented as its own object.
Parameters Parameters are used to provide input to the cmdlet and correspond to one or more properties on an object. The parameters can tell what object to create or act on and specify what properties should be changed on that object, and how they should be changed.
Identity Identity is a special parameter that's used on any cmdlet that lets you retrieve, modify, or remove an object. It gives you access to the unique identifiers that refer to a particular object in Exchange 2010 that you want to view, modify, or remove.
The Identity parameter is also considered a positional parameter, which means that you can specify the parameter's value without specifying the parameter's name. That means that the commands
Get-Mailbox -Identity "JohnE"and
Get-Mailbox "JohnE"are the same to Exchange. A parameter is a positional parameter if the
Parameter Positionattribute is an integer.
Pipelining In the 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. 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 more information about each of these concepts, see Exchange Management Shell Basics in the Exchange 2010 online Help.
Role Based Access Control (RBAC) is the permissions model in Exchange 2010. RBAC uses management roles to define what a user can do. For example, someone who's assigned the
RecipientManagement role can manage mailboxes, contacts, distribution groups, and other types of recipient objects. The management roles that are assigned to users can be scoped to allow users to manage only specific recipients or servers in an Exchange 2010 organization. If that assignment is scoped to only recipients in Seattle, the administrator will only be able to administer Seattle users and nobody else.
|This article discusses a beta release of Exchange 2010 and as such, functionality, composition of built-in roles, and usability are subject to change.|
Exchange 2010 has several built-in management roles that you can use out of the box to distribute permissions to your administrators and users. Some roles, such as
RecipientManagement, enable your administrators to manage other users. Some roles, such as
MyDistributionGroups, enable your end users to manage their own mailbox and distribution groups. Who you assign roles to, and the roles each user is assigned, defines what each user can do in your organization.
RBAC and the Shell
So why is RBAC important in the Shell? As I discuss later in this article, when the Shell is started, it connects to an Exchange 2010 server and authenticates you. As part of the authentication process, Exchange 2010 checks RBAC to see what roles you're assigned. Each management role has a list of cmdlets and their parameters that users assigned the role can use. When the Shell creates your environment, only the cmdlets and parameters that you can access are added to the environment.
The following diagram shows how both the EMC and the Shell connect to an Exchange 2010 server. The request for authentication is received by RBAC, which determines which roles you have, and therefore which cmdlets and parameters you have access to. On subsequent requests, Windows PowerShell and RBAC receive requests to run cmdlets, validate that the user is allowed to run the cmdlet, and then runs the cmdlets for the user.
It's important to understand that, depending on what management roles each user holds, he or she may only see a subset of all the cmdlets that ship with Exchange 2010. For example, the
OrganizationManagement role is the role that can manage every aspect of the Exchange 2010 organization. As such, the
OrganizationManagement role has access to almost every cmdlet and parameter that Exchange 2010 provides. By comparison, the
DiscoveryManagement role is the role that enables users to search mailboxes for specific information.
DiscoveryManagement is a role with a very specific function, and only a few cmdlets and parameters are required to do it. This means that someone who's assigned the
OrganizationManagement role will see far more cmdlets and parameters than the user who's assigned the
|The Help in the Shell and online always shows all the parameters available on the cmdlet, regardless of the roles that the user is assigned.|
Making Exchange Permissions Yours
When you assign roles to your users, think about their job roles and assign the management role that most closely matches their job. If you need to, you can assign more than one role to each user if the combination of roles better matches your user's job. If you have multiple users that share the same job role, think about adding them to a universal security group (USG) and then assigning the needed roles to that USG. That way, you just need to add and remove members from that USG to control permissions.
Finally, while Exchange 2010 provides many built-in roles, those roles might not be a perfect fit for your organization. If that's the case, you can create your own custom roles. RBAC enables you to copy a built-in role and then remove cmdlets and parameters to create a new role that can only do the things you want it to do. For example, if you want a help desk team to be able to create new mailboxes, but unable to specify which database mailboxes are created on, create a new role without the
Database parameter on New-Mailbox or Enable-Mailbox.
For more information about RBAC, see Understanding Role Based Access Control.
As I mentioned earlier, the Shell is built on Windows PowerShell. When you open the Shell using the Exchange Management Shell shortcut, Windows PowerShell opens and some scripts are run. The scripts find the most suitable Exchange 2010 server and connect to it. During the connection process, Exchange checks to see if you're allowed to connect. If you are allowed to connect, Exchange then finds out what RBAC management roles you've been assigned. Finally, it creates an environment that contains all the cmdlets that you're allowed to use and you're ready to go.
Why is all this important to you? If you start Windows PowerShell without using the Exchange Management Shell shortcut and try to run an Exchange cmdlet, such as Get-Mailbox, you’ll get an error. Why? Because the Get-Mailbox cmdlet doesn’t exist in the core set of Windows PowerShell cmdlets. Get-Mailbox must be added by the Shell after it's connected to an Exchange 2010 server for you to use it.
So first things first: Let's open the Exchange Management Shell. Just click Start, click All Programs, Microsoft Exchange Server 2010, and then Exchange Management Shell.
You'll see the Exchange Management Shell (Local PowerShell) option in the Microsoft Exchange Server 2010 menu. The local Windows PowerShell version of the Exchange Management Shell uses a Windows PowerShell snap-in that contains all the cmdlets available with Exchange 2010. It doesn't use the remoting capabilities of Windows PowerShell, and it uses a limited version of RBAC. |
Use the Exchange Management Shell (Local PowerShell) shortcut to use the Shell on an Edge Transport server. If you open the Shell on any server role other than an Edge Transport server, we encourage you to avoid using the Local PowerShell version of the Shell unless you run into a problem that can only be solved by using that option.
The local version of the Shell is removed from all server roles in future versions of Exchange 2010, except for the Edge Transport server role.
The following screenshot shows the Shell connecting to an Exchange 2010 server and importing the cmdlets that the user has access to.
Windows PowerShell will open, and you'll see it connect to an Exchange 2010 server and then load all the cmdlets and parameters that you have access to based on the RBAC management roles assigned to you. After you're connected, you can run cmdlets as usual. The Get-Command cmdlet is useful if you want to see a list of cmdlets that you have access to.
For Exchange 2010, the Microsoft Exchange User Education team has developed a robust set of documentation, available inside the Exchange Management Shell and online.
In the Shell, you'll find that the Get-Help cmdlet is an invaluable resource as you learn to navigate the Shell. Be sure to check out the online Help also. It includes topics that explain all the features in Exchange and how to use the Shell to manage them. You can access the Exchange 2010 online Help at Microsoft Exchange Server 2010 Beta.
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*.
The Getting Help topic in the Exchange Server 2010 online Help lists all the role, component, and functionality values that can be used.
Every time you refresh a view by clicking on a new item or change something, such as a mailbox, the Exchange Management Console runs a Shell command. The EMC in Exchange 2010 has a couple of new features that show you how it uses Shell commands to complete the actions you perform.
The Windows PowerShell Command Log logs every Shell command that's run whenever you do something in the EMC. You can start the log any time after you open the EMC. It stays open and continues to log commands until you either stop the logging or the EMC is closed. If you want to capture logs, you need to start the log each time you open the EMC.
The log contains the following information for each command that's recorded:
Start Execution Time This field records the time the Shell command started running.
End Execution Time This field records the time the Shell command ended.
Execution Status This field records whether the command completed successfully.
Command This field records the command that was run. The cmdlet, the parameters, and their values are included.
To help you view the details of each command that's run, when you select a command, it's displayed in the window below the list of log entries. If the command includes any output, it's also displayed in this window.
You can output the log to a log file, or copy the commands to the Clipboard to use the command in the Shell directly.
The Exchange Management Shell Command window can be accessed when you're making changes to the properties of an object. You can access the Shell Command window by clicking the icon after you've made a change in the Properties window. The Shell Command window displays the command that would be run if you applied the changes you made in the Properties window. The command includes the cmdlet, the parameters, and their values. You can copy the command into the Clipboard and use the command in the Shell directly.
Finally, all the wizards in the EMC include the command that's created when you use the wizard to create or modify an Exchange object. As with the other ways the EMC exposes Shell commands, the wizard completion window shows the command that would be run. It can also be copied to the Clipboard for use in the Shell directly.
By default, when command output is displayed to the screen, the Shell displays only a subset of the available properties for each object. Why? Because each object can contain dozens of properties, and the Shell optimizes the display to include only those properties that are likely to be most useful to you. However, you can easily access and view all the properties of an object 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*.
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.
You can also specify a wildcard character "*" with a partial property name with both the Format-List and Format-Table cmdlets. 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 Email* returns all properties that begin with
Less typing and more time to play with Exchange 2010!
To learn more about Exchange 2010 and the Exchange Management Shell, see the following resources:
Microsoft Exchange Server 2010 Beta: In-depth product documentation.
Microsoft Exchange Server 2010 Forum: Community-driven forums dedicated to discussion and community support of Exchange Server 2010.
Exchange Management Shell: Information to get you up and running with the Shell.
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 - Senior Technical Writer, Microsoft Exchange Server User Education