This documentation is archived and is not being maintained.

Backup and Restore Architecture

EWS Managed API

Topic Last Modified: 2008-04-14

The Exchange Storage Engine (ESE) manages the storage groups and databases used by Microsoft® Exchange Server 2007 . To support higher performance and better integration with disaster recovery systems, the ESE includes an application programming interface (API) for backup and restore.

Each storage group that is mounted simultaneously by Exchange is handled by a single ESE instance. Although Exchange can accommodate up to four storage groups at the same time, ESE supports up to sixteen simultaneous instances. The extra twelve instances can be used to improve restore performance to the storage groups and databases being served by Exchange. Note, however, that the 12 extra ESE instances cannot be used for backup operations.

The ESE backup and restore system supports backup and restore of entire storage groups, as well as individual databases within the storage groups. Because each storage group uses a single set of log files covering all of the databases in the storage group, restore and recovery operations should be done over the entire storage group.

Backing up databases individually provides greater storage management flexibility. For example, critical databases might be backed up to faster media, or backed up more frequently. Infrequently used or less critical databases might be backed up to slower media, or less frequently. Restoring the storage group, however, should combine the archives and logs from all of the appropriate storage media, so that the database can be restored and recovered with minimal data loss.

Applications that use the ESE backup and restore API must run under the security context of a user that has backup and restore privileges on both the source and destination computers.

Microsoft Exchange Server 2007 Service Pack 1 disables remote streaming backup and restore by default. To enable remote streaming backup and restore, set the Windows registry key HKLM\System\CCS\Services\MSExchangeIS\ParametersSystem\Enable Remote Streaming Backup to 1. When that registry key is not present, or is set to 0, remote streaming backup and restore is disabled.

The ESE backup and restore API can run within an application either locally on the computer running Exchange, or remotely over a network. Note, however, that when it is run remotely, data is passed between client and server using remote procedure call (RPC), which is an unencrypted transfer mechanism.

RPC is transmitted over the wire as unencrypted data. Creating backup and restore applications that transmit unencrypted data from Exchange databases is not recommended. Unencrypted data can be monitored easily as it travels through the network. Instead, consider creating your backup and restore applications so that the esebcli2 interface is used only locally on the computer running Exchange. If it is necessary to transmit the data over a network, use only encrypted transmission methods.

The following general information applies to both backup and restore operations.

The backup and restore API is accessed programmatically through the esebcli2 dynamic-link library (DLL). The header file for the API is contained in the esebcli2.h file, shipped in the Microsoft Platform Software Development Kit (SDK), and installed into the include folder under the Platform SDK installation folder.

Many of the esebcli2 functions return HRESULT error code. To retrieve the corresponding error string for these errors, use the standard Microsoft Windows® FormatMessage function. In addition, some functions may require use of the GetLastError function to retrieve the actual error message. Refer to the individual esebcli2 functions for more information about the errors they return.

One of the first steps in working with the backup and restore API is to retrieve the list of servers, storage groups, and databases that are accessible for backup or restore. When working with the list of servers returned by the HrESEBackupPrepare Function, some of those nodes may be virtual servers. Be sure your application checks the node type before displaying the list of servers.

When your application requests the list of applications running on a computer running Exchange that are available for backup or restore, the returned list can contain up to three services. The API refers to these services as "EndPoint Annotations". There can be up to three endpoint annotations, and each will have its wszDisplayName set to "Microsoft Exchange Server". The services can be distinguished by the wszEndpointAnnotation string, which will be one of "Microsoft Information Store", "Microsoft Site Replication Service", or "Microsoft Key Management Service". For most Exchange backup and restore applications, only the "Microsoft Information Store" will be passed on to the HrESEBackupPrepare Function.

In an application, the process of selecting databases for backup and restore has two parts. In addition to getting the list of nodes, storage groups, and databases, the application user interface must provide useful and consistent information to help the user select what parts of their Exchange deployment to work with. To better support consistent representation of item types in the application graphical user interface, the API returns icons for the high-level item types. Individual database files and logs do not have icons defined by ESE, but it is expected that users will not be selecting individual database, stream, and log files.

Reading data from the database files for backup is performed through the ESE backup and restore API. The backup API uses shared memory when the backup application is on the same computer as the ESE instance, for improved performance.

However, in nearly all cases, restore operations use standard Windows file system operations to replace the files. Nonetheless, it is important to tell the ESE which files your application is restoring. The ESE must know which log files have been restored, so that it can recover the databases correctly.

The backup and restore API does not support using double-byte character set (DBCS) characters in file names or in folder paths. However, DBCS is supported in parameters that are intended for display names.

During setup, Exchange 2007 places the file esebcli2.doc in the SDK\Support\Backup folder under the Exchange installation folder. This documentation is obsolete, and inaccurate in some areas. The most up-to-date information is located in the Exchange Software Development Kit. To access the most up-to-date information, see the Exchange Server Developer Center.