Exchange Server 2010 : Using the Exchange Management Shell

Microsoft Internet Information Services (IIS) handles every incoming request to a Web site within the context of a Web application. A Web application is a software program that delivers Web content to users over HTTP or HTTPS. Each Web site has a default Web application and one or more additional Web applications associated with it. The default Web application handles incoming requests that aren't assigned to other Web applications. Additional Web applications handle incoming requests that specifically reference a particular application.

When you connect to a server using a URL, such as https://mailserver15.cpandl.com/powershell, you are performing remote operations via the PowerShell application running on the Web server providing Exchange services. Like all Web applications, the PowerShell application has a virtual directory associated with it. The virtual directory sets the application name and maps the application to the physical directory that contains the application's content.

You can manage the PowerShell application using IIS Manager and the Exchange Management Shell. The related commands for the Exchange Management Shell are:

At the Exchange Management Shell prompt, you can confirm the location of the PowerShell application by typing get-powershellvirtualdirectory .

Get-PowerShellVirtualDirectory lists the name of the application, the associated directory and Web site, and the server on which the application is running, as shown in the following example:

Name                              Server
-------                           -------
PowerShell (Default Web Site)     CorpServer45

In this example, a standard configuration is being used where the application named PowerShell is running on Default Web Site on CorpServer45. You can use Set-PowerShellVirtualDirectory to specify the internal and external URL to use as well as the permitted authentication types. Authentication types you can enable or disable include basic authentication, Windows authentication, certificate authentication, and Live ID basic authentication. You can use New-PowerShellVirtualDirectory to create a new PowerShell application on the Web server providing services for Exchange and Remove-PowerShellVirtualDirectory to remove a PowerShell application.

Now that you know how the Exchange Management Shell environment works, you can more easily customize the shell to work the way you want it to. One way to do this is to modify the menu shortcut that starts the Exchange Management Shell or create copies of this menu shortcut to change the way the Exchange Management Shell starts. For example, if you want to connect to a named Exchange server rather than any available Exchange server, you can do the following:

That said, this entire sequence of tasks is meant to simplify the task of establishing an interactive remote session with a single Exchange server. As implemented in the default configuration, you have a one-to-one, interactive approach for remote management, meaning you establish a session with a specific remote server and work with that specific server simply by executing commands.

When you are working with PowerShell outside of Exchange Management Shell, you might want to use the Enter-PSSession cmdlet to start an interactive session with an Exchange server or any other remote computer. The basic syntax is Enter-PSSession ComputerName, where ComputerName is the name of the remote computer, such as the following:

enter-pssession maileserver15

After you enter this command, the command prompt changes to show that you are connected to the remote computer, as shown in the following example:

[Server49]: PS C:\Users\wrstanek.cpandl\Documents>

Now, the commands that you type run on the remote computer just as if you had typed them directly on the remote computer. In most cases, you need to ensure you are running an elevated, administrator shell and that you pass credentials along in the session. When you connect to a server in this way, you use the standard PowerShell remoting configuration and do not go through the PowerShell application running on a Web server. You can end the interactive session by using the command Exit-PSSession or typing exit.

To access an Exchange server in the same way as the ConnectFunctions.ps1 script, you need to use the –ConnectionURI parameter to specify the connection URI, the –ConfigurationName parameter to specify the configuration namespace, the –Authentication parameter to set the authentication type to use, and optionally, the –SessionOption parameter to set session options. Consider the following example:

enter-pssession -connectionURI http://mailserver12.cpandl.com/powershell
-ConfigurationName Microsoft.Exchange -Authentication Kerberos

Here, you set the connection URI as https://mailserver12.cpandl.com/powershell, set the configuration namespace as Microsoft.Exchange, and use Kerberos authentication with the implicit credentials of your user account. If you don't specify the authentication method, the default authentication method for WinRM is used. If you want to use alternate credentials, you can pass in credentials as shown in this example:

$cred = get-credential -credential adatum\williams

enter-pssession -connectionURI https://mailserver12.cpandl.com/powershell
-ConfigurationName Microsoft.Exchange -credential $cred
-Authentication Kerberos

Here, you set the connection URI as https://mailserver12.cpandl.com/powershell, set the configuration namespace as Microsoft.Exchange, and use alternate credentials. When PowerShell reads the Get-Credential command, you are prompted for the password for the specified account. Because the authentication type is not defined, the session uses the default authentication method for WinRM.

To put this all together, one way to create a script that runs on an Exchange server is to load the Microsoft.Exchange.Management.PowerShell.E2010 snap-in, run the RemoteExchange.ps1 profile file, and then run the ConnectFunctions.ps1 script to autoconnect to Exchange. The commands you insert into your script to do this are the following:

Add-PSSnapin Microsoft.Exchange.Management.PowerShell.E2010
$s = $env:ExchangeInstallPath + "bin\RemoteExchange.ps1"
&$s
$t = $env:ExchangeInstallPath + "bin\ConnectFunctions.ps1"
&$t

Here, you use the Add-PSSnapin command to load the Exchange snap-in. Next, you define variables that point to the RemoteExchange.ps1 and ConnectFunctions scripts in the Exchange installation path, and then you use the & operator to invoke the scripts. The environment variable ExchangeInstallPath stores the location of the Exchange installation. If you enter the full path to a script, you don't need to assign the path to a variable and then invoke it. However, you then have a fixed path and might need to edit the path on a particular Exchange server. Be sure to run the script at an elevated, administrator PowerShell prompt.

If you want to create a script that runs on your management computer and then executes commands remotely on an Exchange server, you'll probably want to insert commands in your script to create a new session and then invoke commands in the session using the techniques discussed in the next section.

PowerShell also lets you perform one-to-many remote management. Here, you must work with an elevated, administrator shell and can either invoke remote commands on multiple computers or establish remote sessions with multiple computers. When you remotely invoke commands, PowerShell runs the commands on the remote computers, returns all output from the commands, and establishes connections to the remote computers only for as long as is required to return the output. When you establish remote sessions, you can create persistent connections to the remote computers and then execute commands within the session. Any command you enter while working in the session is executed on all computers to which you are connected, whether this is 1 computer, 10 computers, or 100 computers.

The following command entered as a single line invokes the Get-Service and Get-Process commands on the named servers:

invoke-command -computername MailServer12, MailServer21, MailServer32
-scriptblock {get-service; get-process}

The following command establishes a remote session with the named computers:

$s = new-PSSession -computername MailServer12, MailServer21, MailServer32
-Credential Cpandl\WilliamS

When you connect to a server in this way, you use the standard PowerShell remoting configuration and are not going through the PowerShell application running on a Web server. After you establish the session, you can then use the $s session with Invoke-Command to return commands on all remote computers you are connected to. In this example, you look for stopped Exchange services on each computer:

invoke-command -session $s
-scriptblock {get-service mse* | where { $_.status -eq "stopped"}}

In this example, you pipe the output of Get-Service to the Where-Object cmdlet and filter based on the Status property. As the $_ automatic variable operates on the current object in the pipeline, PowerShell examines the status of each service in turn and lists only those that are stopped in the output.

In addition to working with remote commands and remote sessions, some cmdlets have a –ComputerName parameter that lets you work with a remote computer without using Windows PowerShell remoting. PowerShell supports remote background jobs as well. A background job is a command that you run asynchronously in an interactive or noninteractive session. When you start a background job, the command prompt returns immediately and you can continue working while the job runs. 

Finally, compared to all the behind-the-scenes tasks that are performed when you work with the Exchange Management Shell, the Forefront Management Shell is very simple. When you select the related menu item, Windows runs PowerShell and loads the FSSPSnapin. Because PowerShell is run with no security context, you won't be able to perform administrative tasks. To resolve this, you need to right-click the Forefront Management Shell and then select Run As Administrator to open an elevated, administrator shell. If you want to run Forefront commands while working with the Exchange Management Shell, all you need to do is type the following command:

Add-PSSnapin FSSPSSnapin

Adding this command to your scripts allows you to work with Forefront Security in your scripts as well.

Note that the ConnectionFunctions.ps1 script relies on your organization having a standard Exchange Server configuration. By default, Exchange is configured for management using HTTP with the URL http://ServerName/powershell. If you've modified the Web Server configuration on your Exchange servers to use a different path, such as might be required to enhance security, you need to update the connection URIs used in the ConnectionFunctions.ps1 script.

When you invoke the PowerShell application, the Web server to which you connect runs the PowerShell plug-in (Pwrshplugin.dll) and the Exchange Authorization plug-in (Microsoft.Exchange.AuthorizationPlugin.dll). The PowerShell plug-in runs as a Microsoft.Exchange shell and has the following initialization parameters:

The Authorization plug-in handles Exchange authorization and authentication. Together, these plug-ins create an authorized shell environment for the remote session.

The physical directory for the PowerShell application is %ExchangeInstallPath%\ClientAccess\PowerShell. This application runs in the context of an application pool named MSExchangePowerShellAppPool. 

In the %ExchangeInstallPath%\ClientAccess\PowerShell directory on your server, you'll find a web.config file that defines the settings for the PowerShell application. This file contains a role-based access control (RBAC) configuration section that loads the assemblies and Web controls for the application.

The Web Server to which you connect processes your remote actions via the Exchange Control Panel (ECP) application running on the default Web site. The physical directory for this application is %ExchangeInstallPath%\ClientAccess\Ecp. This application runs in the context of an application pool named MSExchangeECPAppPool.

In the %ExchangeInstallPath%\ClientAccess\ECP directory on your server, you'll find a web.config file that defines the settings for the ECP application. This file contains an RBAC configuration section that loads the assemblies and Web controls for the application.

Because of the interdependencies created by accessing Exchange via Web applications, you'll want to examine related features as part of troubleshooting any issues you experience with remote sessions. Generally, your troubleshooting should follow these steps: