Managing Exchange 2003 with WMI, Part 1

Like most Windows products released in 2003, Exchange Server 2003 offers more manageability through Windows Management Instrumentation (WMI). As Web Table 1 (http://www.winnetmag.com/microsoftexchangeoutlook, InstantDoc ID 40755) shows, Exchange 2000 Server was the first release in which Microsoft implemented WMI interfaces for Exchange. The original release offered three WMI providers: ExchangeRoutingTableProvider, ExchangeQueueProvider, and ExchangeClusterProvider. These providers are available from the RootCIMV2ApplicationsExchange namespace. Later, Microsoft released Exchange 2000 Service Pack 2 (SP2), which introduced two new WMI providers in the RootMicrosoftExchangeV2 namespace: ExchangeDsAccessProvider and ExchangeMessageTrackingProvider.

Little difference exists between the five providers in Exchange 2000 SP2 and those same five providers in Exchange 2003. The only noticeable change is that Microsoft updated the ExchangeMessageTrackingProvider's Exchange_MessageTrackingEntry class by adding values to the class's EntryType property. To view the documentation on the EntryType property's possible values, go to the Microsoft Developer Network (MSDN) Web site at http://msdn.microsoft.com/library/en-us/e2k3/e2k3/_wmiref_pr_exchange_messagetrackingentryentrytype.asp.

In addition to the five WMI providers found in Exchange 2000 SP2, Exchange 2003 offers five new WMI providers in the RootMicrosoftExchangeV2 namespace: ExchangeFolderTreeProvider, ExchangeMapiTableProvider, ExchangePublicFolderProvider, ExchangeQueue2Provider, and ExchangeServerProvider. So, when you install Exchange 2003, you're installing a total of 10 WMI providers, which support more than 20 WMI classes in various management areas of Exchange 2003.

Any WMI consumer (i.e., any application that can access and use WMI data) can use the WMI classes that the Exchange 2003 installation adds to the Common Information Model (CIM) repository. Therefore, a Windows Script Host (WSH) script, a WMI event consumer provider (e.g., SMTP permanent event consumer), or enterprise-management software (e.g., HP OpenView Operations for Windows) can act as a WMI consumer. Let's look at how to use WSH scripts to access and use the Exchange 2003 WMI management information. I discuss only the new providers that Exchange 2003 adds. I won't discuss the five original Exchange WMI providers because they're well documented. If you're interested in more details, see the Microsoft article "Automating Exchange 2000 Management with Windows Script Host" (http://www.microsoft.com/technet/prodtechnol/exchange/exchange2000/maintain/featusability/ex2kwsh.asp?frame=true). For the same reason, I won't cover WMI basics. If you're unfamiliar with WMI, check out the references at http://msdn.microsoft.com/library/en-us/wmisdk/wmi/further_information.asp.

Exchange 2003's five new providers support 15 new WMI classes. These providers and their classes fall into the following categories:

Because these categories cover a lot of material, I'm splitting this article into three parts. I'll cover the first three categories in Part 1, the fourth category in Part 2, and the fifth category in Part 3.

Exchange Server Management
For Exchange server management tasks, you use the ExchangeServerProvider. This provider supports the Exchange_Server class, which let's you retrieve information about an Exchange 2003 server, such as the server's Administrative Group or Exchange version.

Let's begin by looking at how you use the Exchange_Server class to perform a simple task: obtaining a list of all the available Exchange servers in an organization. The article "Exchange 2000 SP2 WMI Updates," January 2003, http://www.winnetmag.com/microsoftexchangeoutlook, InstantDoc ID 27211, includes a script named GetCollectionOfInstances.wsf, which uses a WMI Query Language (WQL) query to list all instances of a class. If you run the command

GetCollectionOfInstances.wsf"Select * From Exchange_Server"/NameSpace:RootMicrosoftExchangeV2

from the command-shell window, you can obtain a list of all the available Exchange servers in your organization. Note that the script shows only those properties that have a value. Web Figure 1 (http://www.winnetmag.com/microsoftexchangeoutlook, InstantDoc ID 40755) shows sample data from running GetCollectionOfInstances.wsf against the Exchange_Server class.

You can download GetCollectionOfInstances.wsf as well as all the other scripts discussed in this article from the Exchange & Outlook Administrator Web site. Go to http://www.winnetmag.com/microsoftexchangeoutlook, enter InstantDoc ID 40755 in the InstantDoc ID box, then click Download the Code. To run GetCollectionOfInstances.wsf and the other scripts in this article, you must have Administrator permission if the namespace is accessed remotely or user permission if you access the namespace locally. If you use the user permission, make sure you can log on locally to the server.

Although learning about an Exchange server is interesting, being able to update that information would be more helpful. Using the Exchange_Server class's four read/write properties (i.e., AdministrativeNote, Message-TrackingLogFileLifetime, MonitoringEnabled, and SubjectLoggingEnabled) and two methods (i.e., MoveMTAData and EnableMessageTracking), you can do just that. For example, let's look at how you can use the AdministrativeNote property to update an Exchange server's administrative note and the EnableMessageTracking method to enable message tracking on an Exchange server.

Using the AdministrativeNote property. The script AdminNote.wsf, which Listing 1 shows, is a Windows Script (WS) file that leverages the AdministrativeNote property and the XML features that WSH 5.6 provides. The script uses the TinyErrorHandler.vbs file, which contains the ErrorHandler function. This function helps handle errors that occur during script execution.

Next, AdminNote.wsf creates an SWbemLocator object, which the script uses for the WMI connection. As the code at callout A in Listing 1 shows, the script uses a user ID and password to complete the WMI connection. When the user ID and password are empty strings, the script makes the connection under the security context of the user who's running the script. If you need to run the script under a different security context, you can add a user ID and password in the code at callout A.

Callout A highlights two additional lines that you must customize before you run AdminNote.wsf. First, you must change the cComputerName constant's value to the Fully Qualified Domain Name (FQDN) of an Exchange computer in your organization. In addition, you'll probably want to change the cAdministrativeNote constant's string to a more suitable administrative note.

After establishing the WMI connection, AdminNote.wsf uses the cComputerName constant's FQDN to retrieve an instance of the Exchange_Server class. This instance represents an Exchange 2003 server and its set of information (e.g., the Administrative Group, Exchange version, message-tracking status). Next, the script displays the current value of the AdministrativeNote property, after which it replaces that value with the value assigned to the cAdministrativeNote constant. The script then updates the Exchange_Server instance by invoking the Put_method, which the SWbemObject exposes. (If you're unfamiliar with the SWbemLocator or SWbemObject objects, you can learn about them at http://msdn.microsoft.com/library/en-us/wmisdk/wmi/scripting_api_objects.asp.) After the script saves the instance, the change is visible in Exchange System Manager (ESM).

You can adapt AdminNote.wsf to update the other read/write properties of the Exchange_Server class. Only the name of the property to update and its respective data type will vary (e.g., string data versus Boolean data when appropriate). Callout B in Listing 1 highlights the line to change to read a different property. Callout C in Listing 1 highlights the line to change to update a different property.

AdminNote.wsf is a simple script that demonstrates a structure that's common to most of the WSH WMI scripts in this article. Therefore, I discuss only variations of this structure that won't be familiar to you.

Using the EnableMessageTracking method. The EnableMessageTracking method lets you enable or disable message tracking on an Exchange server. The script MessageTracking.wsf, which Listing 2 shows, illustrates how to use the EnableMessageTracking method. The overall logic of the code is basically the same as that in AdminNote.wsf. The major change resides in the method invocation. As the code at callout B in Listing 2 shows, the EnableMessageTracking method requires two parameters. The first parameter is a Boolean value that enables (True=Enabled) or disables (False=Disabled) message tracking. The second parameter is a string that specifies the message-tracking log's pathname. The script uses constants (cMessageTrackingEnabled and cMessageTrackingLogFilePath, respectively) to provide both of these parameters.

If you want to use this script, you need to customize the cMessageTrackingEnabled and cMessageTrackingLogFilePath constants as well as the other constants that callout A in Listing 2 highlights. If you want to use the MoveMTAData method to move Message Transfer Agent (MTA) files to another location, you can adapt MessageTracking.wsf by changing the invoked method and the input parameters. You can find the documentation for both methods at http://msdn.microsoft.com/library/en-us/e2k3/e2k3/_wmiref_cl_exchange_server.asp.

Exchange Logon Management
For Exchange logon management tasks, you use the ExchangeMapiTableProvider. This provider supports the Exchange_Logon class, which represents the users currently logged on to an Exchange 2003 server. The Exchange_Logon class has a set of read-only properties and doesn't have any method. The documentation for the properties is available from Microsoft at http://msdn.microsoft.com/library/enus/e2k3/e2k3/_wmiref_cl_exchange_logon.asp. You can use GetCollectionOfInstances.wsf with the WQL query

"Select * From Exchange_Logon"

to obtain a list of all instances and properties of the Exchange_Logon class. You can limit the scope of the query to a specific mailbox by specifying the mailbox's display name. To do so, you use the Where statement in a WQL query, such as

"Select * From Exchange_Logon  Where MailboxDisplayName=  'LISSOIR Alain'"

Web Figure 2 shows sample data from running this query.

You can gather a lot of mailbox and user information from this output. For example, you can learn about the user account (LoggedOnUserAccount property) that's connected to the mailbox, the store to which the user is connected (StoreName property), the IP address of the client (ClientIP property), and the client software version (ClientVersion property), which corresponds to Microsoft Office Outlook 2003. Note that with earlier versions of Outlook and with Internet protocol-based clients such as Outlook Express, not all properties are initialized. For non­Messaging API (non-MAPI) clients, the client version might be SMTP or OLE DB. You can have more than one connection listed in the output. For example, you can have two connections: one to the mailbox store and one to the public folder store. The output often shows several Exchange_Logon instances for one client. Therefore, to be exact, the Exchange_Logon class represents the client connections more than it represents the client logons, even if it presents some logon information, such as the LogonTime property.

Although the output in Web Figure 2 is useful for tracking messages, tracking user logons only when users log on to Exchange can be more revealing. To show the properties of the Exchange_Logon class only at that time, you must use a different WQL query, called a WQL event query. "Exchange 2000 SP2 WMI Updates" provides a script called GenericEventAsyncConsumer.wsf that submits such a query. Therefore, to obtain the same information as before but only at logon time, you use the WQL query

"Select * From   __InstanceOperationEvent  Within 10 Where  TargetInstance ISA'Exchange_Logon' AndTargetInstance.MailboxDisplayName=  'LISSOIR Alain'"with GenericEventAsyncConsumer.wsf.

Exchange Mailbox Management
For Exchange mailbox management tasks, you use the ExchangeMapiTableProvider's Exchange_Mailbox class. This class provides a series of read-only properties and two methods (i.e., Purge and Reconnect) that you can use to manage mailboxes. The documentation for the Exchange_Mailbox properties and methods is at http://msdn.microsoft.com/library/en-us/e2k3/e2k3/_wmiref_cl_exchange_mailbox.asp.

Some of the Exchange_Mailbox properties return mailbox-related information, such as the last logon time (LastLogonTime property), the last logoff time (LastLogoffTime property), and the name of the last user who logged on to the mailbox (LastLoggedOnUserAccount property). Other Exchange_Mailbox properties provide information about the mailbox location on the Exchange server. This information includes the server name (ServerName property), storage group (SG) name (StorageGroupName property), and store name (StoreName property). The Exchange_Mailbox class also exposes information about the size (in bytes) of a mailbox (Size property) and the number of items in the mailbox (TotalItems property).

The Purge and Reconnect methods' roles relate to fixing orphaned mailboxes. (You must handle other mailbox management tasks, such as creating, moving, or deleting an Exchange mailbox, through Collaboration Data Objects for Exchange Management—CDOEXM.) If an administrator uses the Microsoft Management Console (MMC) Active Directory Users and Computers snap-in to delete a user account but doesn't delete the mailbox, the mailbox is left in a disconnected state. After Exchange's Cleanup Agent runs, the mailbox in the Exchange Mailbox store is left without a user assigned to it. At that time, Exchange gives the administrator the chance to physically delete the mailbox from the store, which is the aim of the Purge method, or to reconnect the mailbox to an existing user, which is the aim of the Reconnect method.

The script Reconnect.wsf demonstrates how to use the Reconnect method to reconnect an Exchange mailbox to an existing user account. The structure of Reconnect.wsf is similar to that of AdminNote.wsf. However, slight differences exist. The script header starts with the definition of two constants: cMailboxDisplayName, which specifies the display name of the mailbox to reconnect, and cUserAccount, which specifies the user account to which to reconnect the mailbox.

To locate the mailbox, the script uses a WQL query, such as

"Select * From Exchange_Mailbox  Where MailboxDisplayName=  'LISSOIR Alain'"

After this query executes, the script enumerates a collection of mailboxes that match the selection criterion. In other words, the script isolates the mailbox by using a property whose value isn't guaranteed to be unique. Although you could specify the mailbox's globally unique identifier (GUID), which is guaranteed to be unique, in the MailboxGUID property, using the mailbox's display name is easier. Trying to find a mailbox's GUID, then trying to enter it without an error, would make the script difficult to use.

Because the mailbox name might not be unique, the script checks to see whether the collection contains only one mailbox, as the code excerpt in Listing 3 shows. If the script finds more than one mailbox, it displays a message that informs the operator about the ambiguity. If the script finds only one mailbox, it executes the Reconnect method. This method has two required parameters, which the script supplies through the cMailboxDisplayName and cUserAccount constants.

Although the WQL query I just showed you finds the mailbox, you don't have any guarantee that the mailbox is disconnected from a user. To determine whether a mailbox is disconnected, you can use the Exchange_Mailbox class's DateDiscoveredAbsentInDS property. This property indicates when the store detected that the mailbox no longer had a corresponding user account. When this property contains a date in the Distributed Management Task Force (DMTF) format, it's a disconnected mailbox. For more information about the DMTF format, go to http://msdn.microsoft.com/library/enus/wmisdk/wmi/date_and_time_format.asp.

To locate a mailbox using a specific display name and to ensure that the mailbox is disconnected, you can use an improved WQL query that narrows the search's scope:

"Select * From Exchange_Logon  Where MailboxDisplayName=  'LISSOIR Alain' And  DateDiscoveredAbsentInDS  IS NOT Null"

Finally, to ensure a successful execution of the Reconnect method, you must follow these guidelines:

If you don't follow these guidelines, the Reconnect mailbox method will fail. You'll get the following error message: An unknown ADSI user object was requested. Make sure you have the required permissions and/or you are running on the Exchange Server to invoke this method.

WMI and CDOEXM
The addition of WMI's providers and classes has improved object management in Exchange 2003. Some WMI classes provide information that you can also obtain with CDOEXM. Take, for example, WMI's Exchange_Server class. The Exchange_Server class's Name property and CDOEXM's Name property both provide the Exchange server's name. Similarly, the Exchange_Server class's ServerType property and CDOEXM's Type property both provide the server's type (i.e., back-end or front-end server). Other Exchange_Server class properties (e.g., the Exchange_Server class's MonitoringEnabled property) and methods (e.g., the Exchange_Server class's MoveMTAData method) nicely complement the CDOEXM features. And the addition of the ExchangeMapiTableProvider WMI provider to Exchange 2003 enhances the management of Exchange in two areas: user logon management and mailbox management. Although these two technologies expose a complementary (and sometimes redundant) set of information, both technologies contribute to the expansion of Exchange server manageability.