Exchange Web Services Developer Overview

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Topic Last Modified: 2008-06-27

Microsoft Exchange Server 2007 introduces Exchange Web Services (EWS), an API that enables developers to create custom client, server, and middleware applications for Exchange without using Microsoft Office Outlook or any server-side code. EWS makes it easy for almost any platform or device that can connect to the Internet to interact with Exchange mailboxes and their contents, including e-mail messages, calendaring items, task items, and contacts, over HTTP or HTTPS.

For those of you who have not yet migrated to Exchange Web Services, you often have to use functionality from various APIs, such as WebDAV, Collaboration Data Objects for Exchange 2000 Server (CDOEX), and the Exchange OLE DB provider (ExOLEDB), to create applications. None of these APIs provide all the elements that you need for your applications, such as remote access over HTTP and access to Outlook business logic. EWS provides a unified, cohesive, open standards–based API that replaces other Exchange APIs, while retaining much of their functionality, and extends them with an Outlook-compatible business logic layer. You can migrate your existing code from other APIs to EWS or integrate EWS into your existing applications to provide most of the same functionality, as well as simplify redistribution and maintenance of your applications.

The following table lists common business requirements for Exchange-compatible applications and indicates which Exchange technologies meet those requirements.

Comparing Exchange Server technologies for common business requirements

Business Requirement	WebDAV	CDOEX	Exchange Web Services
Accesses Microsoft Exchange over HTTP.	Yes	No	Yes
Includes interoperability with Outlook business logic.	No (This must be implemented manually.)	Yes (Includes some native interoperability, but can be extended manually for complete support.)	Yes
Implements the business logic that is required for complex calendaring operations (such as creating recurring meetings, modifying, and canceling meetings).	No (This can be implemented manually.)	No (This can be implemented manually.)	Yes
Runs without requiring custom application code on the Exchange server.	Yes	No	Yes
Provides strong typing.	No	Yes	Yes
Can be used in a managed programming environment such as Microsoft .Net.	Yes	Yes	Yes
Supports automatic proxy class generation that provides an object model that abstracts the transport and underlying XML from the developer.	No	Not applicable.	Yes (EWS is a SOAP- compliant Web service.)
Creates applications that are easily redistributable (no libraries on client computers).	Yes	No	Yes

One advantage of EWS is its built-in compatibility with Outlook. All objects that are created by EWS-based applications (e-mail messages, appointments, folders, and so on) are recognized by and can be opened and manipulated by Outlook and Microsoft Office Outlook Web Access as if they were created by using those applications.

You can use the Add Web Reference feature in Microsoft Visual Studio 2005 to automatically generate proxy classes that comply with the EWS schema. When you use auto-generated proxy classes, you can take advantage of IntelliSense. This minimizes the potential for coding errors and provides an autocomplete feature so that you do not have to remember method names and applicable properties. Visual Studio also enforces strong typing in the compiler when you are using EWS auto-generated proxy classes.

XML-Based Technology

Because Exchange Web Services is based on open standards technologies such as XML, SOAP, and WSDL, Exchange 2007 can interact with any client that can process XML and connect to the Internet. The server does not need any information about the environment in which the client is running. This is an advantage for organizations that run in heterogeneous environments.

EWS communicates with computers that are running Exchange 2007 through SOAP, a widely used, XML-based protocol that is used to request and send information over common transport protocols such as HTTP.

The EWS XML protocol defines a standard messaging format for information exchange between applications and the Exchange server. This format is expressed in the following files:

• Services.wsdl   Describes a contract between the client and the server.
• Messages.xsd   Defines the request and the response SOAP messages.
• Types.xsd   Defines the elements that are used in the SOAP messages.

These files are located in the EWS virtual directory of the Client Access server. Applications have to comply with the definitions in those files to correctly communicate with Exchange.

Most development environments, such as Microsoft Visual Studio 2005, give users a way to automatically generate class libraries that map to the WSDL and schemas of a Web service. Those class libraries implement a set of proxy objects that hide the complexity of manually formatting SOAP messages and manually parsing SOAP responses. This enables you to focus on the core functions of your applications.

Using Exchange Web Services

Exchange Web Services implements a set of Web service methods that includes most of the functionality that an application needs to create and manipulate objects in the Exchange data store, including e-mail messages, attachments, calendar items, contacts, and folders. Specialized Web service methods also interact with the Active Directory directory service and Exchange-specific features such as Out of Office (OOF) scheduling and notifications.

To call an EWS Web service method by using the proxy classes that are generated by Visual Studio 2005, an application instantiates an object that represents the request to be performed and sets its properties. For example, to search for items in a specific folder, an application does the following:

1. Creates and initializes an instance of the ExchangeServiceBinding class, the proxy object that exposes the Web service methods.
2. Creates an instance of the FindItemType class and sets its ItemShape and ParentFolderIds properties.
3. Calls the FindItem operation on the ExchangeServiceBinding object to send the request to the server, which returns a FindItemResponseType object that contains the result of the call to the Web service method.
4. Processes the result.

The following code example shows these steps.

private ExchangeServiceBinding serviceBinding;

// Create an instance of the ExchangeServiceBinding class.
serviceBinding = new ExchangeServiceBinding();
serviceBinding.Credentials = new NetworkCredential(Properties.Settings.Default.UserName,
Properties.Settings.Default.Password, 
Properties.Settings.Default.Domain);
// A production application should call the Autodiscover service to locate the service binding URL.
serviceBinding.Url = Properties.Settings.Default.EWSUrlEndPoint;
List<MessageType> Messages = null;

// Create an instance of the FindItemType class.
// Form the FindItem request.
FindItemType findRequest = new FindItemType();
findRequest.Traversal = ItemQueryTraversalType.Shallow;
// Define which item properties are returned
// in the response.
ItemResponseShapeType itemProperties = new ItemResponseShapeType();
itemProperties.BaseShape = DefaultShapeNamesType.AllProperties;
// Add properties shape to request.
findRequest.ItemShape = itemProperties;
// Identify which folders to search to find items.
DistinguishedFolderIdType[] folderIDArray = new DistinguishedFolderIdType[1];
folderIDArray[0] = new DistinguishedFolderIdType();
folderIDArray[0].Id = DistinguishedFolderIdNameType.inbox;
findRequest.ParentFolderIds = folderIDArray;
// Add folders to request
// the FindItem method on the ExchangeServiceBinding object.
// Send the listing (find) request and get the response.
FindItemResponseType findResp = serviceBinding.FindItem(findRequest);

// Process the result.
// Get the response messages.
foreach (ResponseMessageType responseMessage in findResp.ResponseMessages.Items)
  {
  // Cast to the correct response message type.
FindItemResponseMessageType  
findItemResponseMessage = responseMessage as 
FindItemResponseMessageType;
if (findItemResponseMessage.ResponseClass == ResponseClassType.Success)
{
     // Get the actual payload of items.
     ArrayOfRealItemsType realItems = 
  findItemResponseMessage.RootFolder.Item as 
   ArrayOfRealItemsType;
     if (realItems.Items != null)
     {
        // Initialize list of messages and fill.
     Messages = new List<MessageType>(realItems.Items.Length);
        MessageType message = null;
        foreach (ItemType item in realItems.Items)
        {
          if (item is MessageType)
          {
            message = item as MessageType;
            Messages.Add(message);
          }
        }
     }
  }
}

Folder Operations

Folder operations provide access to folders in the Exchange data store. An application can create, update, delete, copy, find, get, and move folders that are associated with a mailbox user.

Exchange Web Services includes the following folder operations:

• CopyFolder Operation   Creates a copy of a folder.
• CreateFolder Operation   Creates a new folder.
• CreateManagedFolder Operation   Enables users to add managed custom folders to their mailboxes instead of having the administrators do it for them.
• DeleteFolder Operation   Deletes a folder.
• FindFolder Operation   Finds one or more folders, gets a list of subfolders in a folder, and uses search restrictions to narrow the results of a folder search.
• GetFolder Operation   Gets the properties of a folder or set of folders.
• MoveFolder Operation   Moves a folder to another folder or subfolder.
• SyncFolderHierarchy Operation   Synchronizes a folder hierarchy between a mailbox and an application.
• SyncFolderItems Operation   Synchronizes items in a folder between a mailbox and an application.
• UpdateFolder Operation   Updates the properties of a folder.

Starting with Microsoft Exchange Server 2007 Service Pack 1 (SP1), a delegator, also known as a principal, can assign folder-level permissions to delegates to allow the delegate to perform actions on the principal's behalf. For more information about delegate access, see Exchange Web Services and Delegate Access.

Folder-level permissions are supported in the following operations:

• CreateFolder
• GetFolder
• UpdateFolder
• SyncFolderHierarchy

Delegate Management Operations

The delegate management operations enable clients to add, update, get, and remove delegates from their mailbox. These operations were introduced in Exchange 2007 SP1.

Exchange Web Services includes the following delegate management operations:

• AddDelegate Operation   Adds one or more delegates to a principal's mailbox and sets specific access permissions.
• GetDelegate Operation   Retrieves the delegate information for a specific mailbox.
• RemoveDelegate Operation   Removes one or more delegates from a user's mailbox.
• UpdateDelegate Operation   Updates delegate permissions on a principal's mailbox.

Item Operations

The Item operations provide access to items in the Exchange data store. Applications can use these operations to create, update, delete, copy, get, move, and send items.

Exchange Web Services includes the following item operations:

• CopyItem Operation   Creates a copy of an item.
• CreateAttachment Operation   Attaches a file to a mailbox item.
• CreateItem Operation   Creates a new item.
• DeleteAttachment Operation   Removes an existing attachment.
• DeleteItem Operation   Deletes an item.
• FindItem Operation   Searches for an item or items.
• GetAttachment Operation   Retrieves the properties of an existing attachment.
• GetItem Operation   Gets the properties of an item.
• MoveItem Operation   Moves an item to a new folder.
• SendItem Operation   Sends an existing e-mail message.
• UpdateItem Operation   Updates an existing item.

Item operations work on the following item types:

• Message Items   XML representations of e-mail messages that use the Internet Message Format that is defined in RFC2822.
• Contact Items   Represent contacts that are located in private contact stores.
• Task Items   Outlook Personal Information Manager (PIM) objects that can be accessed through the Task pane. Tasks can be single items or recurring activities.
• Calendar Items   Meetings and appointments. Calendar items identify the location, resources, recurrence, and attendees involved at a discrete time. Meeting organizers can create, update, and delete individual and recurring meetings. Organizers can also send out meeting invitations. Meeting attendees can accept, decline, and tentatively accept invitations.

Availability Operations

The Availability operations provide information about a user’s calendar and their free/busy information (scheduled appointments, status, and work hours). These operations also enable applications to retrieve and update OOF settings.

Exchange Web Services includes the following availability operations:

• GetUserAvailability Operation   Retrieves live free/busy information for Exchange 2007 mailboxes, forests, or public folders so that users and resources can be scheduled with more confidence.
• SetUserOofSettings Operation   Sets a user's Out of Office schedule, internal message, and external message.
• GetUserOofSettings Operation   Retrieves a user's Out of Office state, schedule, and messages.

You can use these operations to create applications that have advanced collaboration and scheduling features.

Messaging Records Management Operation

The Messaging Records Management Service consists of a single operation: the CreateManagedFolder Operation.

This operation lets users add managed custom folders to their mailboxes instead of having the administrators do it for them. Managed folders interact with automated processes to retain, expire, or journal e-mail messages based on the compliance and records management policies of an organization. In many organizations, for example, archived e-mail is automatically deleted after 30 days.

Administrators can create managed folders by using the New-ManagedFolder cmdlet in the Exchange Management Shell.

Notification Operations

The Notification service enables applications to be notified of changes in users’ mailboxes. Applications must first subscribe to the Events Notifications subsystem to receive notifications and specify what types of events should be monitored for a mailbox. The Notification operations support both push subscriptions, in which the Exchange server actively notifies applications of changes, and pull subscriptions, in which the applications poll the Exchange server for changes.

Exchange Web Services includes the following notification operations:

• Subscribe Operation   Used to subscribe applications to either push or pull notifications.
• GetEvents Operation   Used by pull subscription clients to request notifications from the Client Access server.
• Unsubscribe Operation   Used to drop a pull notification subscription; can be used instead of letting a subscription time out.

The following events can be monitored by the Event Notification subsystem:

• Mail arrival
• Item creation
• Item deletion
• Item modification
• Item movement
• Item copied
• Mail submission

Synchronization Operations

The Synchronization service provides a one-way, synchronized view of folders and items in a user’s mailbox. The Synchronization service enables applications to know what changes have occurred in the mailbox since a specific point in time. For example, if an application has to keep a local copy of a user's mailbox, this service enables the application to synchronize data in its local version with the data on the Exchange server.

Exchange Web Services includes the following synchronization operations:

• SyncFolderHierarchy Operation   Enables an application to synchronize the folder hierarchy of a mailbox.
• SyncFolderItems Operation   Enables an application to synchronize all items in a folder.

Autodiscover Service

The Autodiscover service enables applications to automatically configure themselves with a Client Access server. Autodiscover provides configuration information inside or outside firewalls and works in resource forest and multiple forest topologies.

Utility Operations

Exchange Web Services includes the following utility operations:

• ExpandDL Operation   Enables applications to retrieve the members of a distribution list.
• ResolveNames Operation   Enables applications to resolve ambiguous names against Active Directory.
• ConvertId Operation   Converts item and folder identifiers between formats that are accepted by Exchange 2007. This method was introduced in Exchange 2007 SP1.

Summary

Exchange Web Services is a comprehensive, standards-based API that enables custom applications to interact with the Exchange store over HTTP. Exchange Web Services also provides a familiar programming interface for developers who have worked with other SOAP Web services and managed code.

Exchange 2007 supports the use of legacy APIs, but there are compelling reasons for you to migrate your existing applications to use Exchange Web Services. Exchange Web Services delivers a more versatile development environment than legacy APIs, extending the business logic from Outlook and Outlook Web Access to custom applications.

As organizations grow, the need for more customized software solutions becomes important and manageability becomes a central issue. Exchange Web Services in Exchange 2007 enables organizations to use a single cohesive API to customize their e-mail solutions to meet their needs. EWS provides a simplified path to Exchange support for new mobile devices and custom desktop applications, now and into the future.

Additional Resources

For more information about Exchange 2007 development, see the following:

• Microsoft Exchange Server
• Exchange Server Developer Center

For more information about Web services, see the following:

• Support WebCast : Microsoft .NET: Introduction to Web Services
• Introduction to Programming Web Services in Managed Code
• Accessing XML Web Services in Managed Code