Introducing the Exchange Web Services Managed API 1.0

Introducing the Exchange Web Servic...

Collapse All

Topic Last Modified: 2009-02-05

Microsoft Exchange Server 2007 introduces Exchange Web Services (EWS), a new API that can be used to access Exchange resources. The EWS API meets the following goals:

Provides unified access to Exchange resources.
Provides a built-in, Microsoft Office Outlook–compatible business logic layer.
Is standards-based.
Is remotable.

EWS combines the functionality that is included in WebDAV and CDOEX, and provides logic that makes common scenarios such as calendaring workflows easy to implement. EWS is a SOAP-based XML Web service that can be accessed remotely from any operating system and any language that can send requests over HTTPS.

Exchange 2007 Service Pack 1 (SP1) introduces several new EWS features that are not included in the initial release version of Exchange 2007, including delegate management and public folder access. Microsoft Exchange Server 2010 will include more new EWS features, including the ability to access Folder Associated Items (FAIs) and User Configuration Objects (objects that let developers store and retrieve user configuration information from a mailbox), full handling of private distribution lists, enhanced time zone support, and more.

EWS is a very powerful API. However, using EWS via autogenerated proxy classes, such as the ones that are generated by the Add Web Reference feature in Microsoft Visual Studio, is less than optimal when it comes to implementing complex applications. The amount of code that must be written can sometimes be quite large. This is because autogenerated proxy classes are a direct map to the underlying protocol. The autogenerated code can be awkward to use (for example, the *specified properties that are generated by Visual Studio). As a result, code that is written by using the autogenerated proxy classes is often difficult to read and maintain.

To address these usability and maintainability issues, we are introducing the Microsoft Exchange Web Services (EWS) Managed API.

First-Class .NET Development for Exchange

The EWS Managed API is a fully object-oriented API that provides the experience developers have come to expect from Visual Studio and the Microsoft .NET Framework. Built on the EWS XML protocol, it provides an easy-to-learn, easy–to-use, and easy-to-maintain .NET interface to Exchange Web Services that both beginner and advanced developers will find to be an improvement over autogenerated proxies.

Although the EWS Managed API is a new API (in the sense that it is a new .NET assembly that developers have to explicitly reference in their applications), it is important to understand that we are not replacing the EWS protocol. The EWS Managed API is just a complement to EWS for .NET developers. This means that your prior investments are safe. Whether you are using raw XML (if you are a Javascript developer, for example) or autogenerated proxies (on Windows or other operating systems) to talk to EWS, your existing EWS applications will continue to work. The EWS protocol is still the future of Exchange development; all new features will continue to be added to the EWS protocol, and will also be exposed in the EWS Managed API.

Just How Easy Is It?

When I say that the EWS Managed API is a big improvement over autogenerated proxies, I really mean it. The following code examples compare the two approaches by showing how to retrieve a folder’s properties, first by using autogenerated proxies, and then by using the EWS Managed API.

Retrieving a folder’s properties by using autogenerated proxies

CSharp

GetFolderType request = new GetFolderType();

request.FolderShape = new FolderResponseShapeType();
request.FolderShape.BaseShape = DefaultShapeNamesType.AllProperties;

DistinguishedFolderIdType inboxId = new DistinguishedFolderIdType();
inboxId.Id = DistinguishedFolderIdNameType.inbox;

request.FolderIds = new BaseFolderIdType[] { inboxId };

GetFolderResponseType response = serviceBinding.GetFolder(request);
FolderInfoResponseMessageType responseMessage =
response.ResponseMessages.Items[0] as FolderInfoResponseMessageType;

if (responseMessage.ResponseClass == ResponseClassType.Success)
{
    FolderType inbox = responseMessage.Folders[0] as FolderType;
}

Retrieving a folder’s properties by using the EWS Managed API

CSharp

Folder inbox = Folder.Bind(service, WellKnownFolderName.Inbox);

EWS Managed API Features

Now that you have seen how easy the EWS Managed API is to use, let's take a look at some of its features.

Binding to EWS

To start to use the EWS Managed API, all that you need is an instance of the ExchangeService class, as shown in the following code example.

CSharp

using Microsoft.Exchange.WebServices.Data;
...
ExchangeService service = new ExchangeService();
service.Credentials = new NetworkCredential("name", "pwd", "domain");
service.Url = new Uri("https://myserver/EWS/Exchange.asmx");

You will find that the ExchangeService class provides many useful methods, such as FindItems, FindAppointments, DeleteItems, and AddDelegates. You can see by the following figure that the EWS Managed API provides full IntelliSense support.

EWS Managed API IntelliSense

Dd637749.db3d3c66-cf7f-45ff-9b1c-06ad58ac140e(en-us,EXCHG.80).gif

And now for some great news: the EWS Managed API also works against Exchange 2007 SP1 servers! Targeting Exchange 2007 SP1 is as easy as passing that version in the ExchangeService constructor, as shown in the following example.

CSharp

ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);

You can use the same version of the EWS Managed API to target multiple versions of Exchange. The same binary can be used against both Exchange 2007 SP1 and Exchange 2010. However, you should be aware that if your application targets Exchange 2007 SP1, the Exchange 2010–specific features will be disabled and an exception will be thrown if you try to use them.

Using Autodiscover

The Autodiscover service is a key part of the Exchange 2007 and Exchange 2010 architecture. With Autodiscover, an application can determine the settings that it should use to communicate with Exchange, such as the URL of Exchange Web Services.

The EWS Managed API provides a built-in Autodiscover client. You no longer have to download the Exchange Server Software Development Kit (SDK) and copy code from the Autodiscover sample application. Invoking Autodiscover is as simple as calling one method, as shown in the following example.

CSharp

ExchangeService service = new ExchangeService();
service.Credentials = new NetworkCredential("name", "pwd", "domain");
service.AutodiscoverUrl("someone@contoso.com");

Exchange 2010 will also introduce a new SOAP-based Autodiscover service, which you can access by using the EWS Managed API, as follows.

CSharp

using Microsoft.Exchange.WebServices.Autodiscover;
...
AutodiscoverService autodiscover = new AutodiscoverService("contoso.com");
autodiscover.Credentials = new NetworkCredential("name", "pwd", "domain");
GetUserSettingsResponse response = autodiscover.GetUserSettings(
   "someone@contoso.com",
   UserSettingName.ExternalEwsUrl,
   UserSettingName.InternalEwsUrl);

Working with Items and Folders

The EWS Managed API exposes all item and folder (including public folders) manipulation features, including creating, updating, getting, and deleting, in an object-oriented way. To see this functionality in action, let's look at some code examples.

Creating a new folder in the Inbox

CSharp

Folder folder = new Folder(service);
folder.DisplayName = "My new folder";
folder.Save(WellKnownFolderName.Inbox);

Creating and saving a draft e-mail message

CSharp

EmailMessage message = new EmailMessage(service);
message.Subject = "Hello from the EWS Managed API";
message.Body = "Now that's easy!";
message.ToRecipients.Add("someone@fabrikam.com");
message.Save();

Sending an e-mail message and save a copy

Note:
Saving a copy of the message is not required.

CSharp

message.SendAndSaveCopy();

Binding to an existing contact and updating it

CSharp

Contact contact = Contact.Bind(service, new ItemId("abcdef"));
contact.CompanyName = "Fabrikam";
contact.Update(ConflictResolutionMode.AutoResolve);

Deleting a contact

CSharp

contact.Delete(DeleteMode.HardDelete);

Creating a recurring meeting

CSharp

Appointment appointment = new Appointment(service);
appointment.Subject = "Play tennis";
appointment.Body = "Let's play tennis for an hour every Saturday at 10AM";
appointment.Start = new DateTime(2008, 12, 20, 10, 00, 00);
appointment.End = appointment.Start.AddHours(1);
appointment.RequiredAttendees.Add("someone@fabrikam.com");
appointment.Recurrence = new Recurrence.WeeklyPattern(
    appointment.Start.Date,
    1 /* Every week */,
    DayOfWeek.Saturday);
appointment.Save(SendInvitationsMode.SendToAllAndSaveCopy);

As these examples show, each item type is exposed through a dedicated class. The same concept applies to folders – each folder type is exposed through a dedicated class. The following images show the item class hierarchy and folder class hierarchy as exposed by the EWS Managed API.

Item class hierarchy

Dd637749.f7170860-2c47-4086-9940-7f3259fbdbf1(en-us,EXCHG.80).gif

Folder class hierarchy

Dd637749.6e7d95db-6639-48b0-b90b-97a780016644(en-us,EXCHG.80).gif

Using Response Objects

With Exchange Web Services, response objects are used to perform actions on items, such as replying to a message or accepting a meeting request. The EWS Managed API encapsulates this concept and exposes it in a very simple way. Let's look at some code examples.

Replying to a message

CSharp

EmailMessage message = EmailMessage.Bind(service, new ItemId("abcd"));
message.Reply("This is my reply!", true /* replyAll */);

Sending a customized reply message and saving a copy

CSharp

ResponseMessage response = message.CreateReply(true /* replyAll */);
response.BodyPrefix = "This is my customized reply!";
response.CcRecipients.Add("someone@fabrikam.com");
response.SendAndSaveCopy();

Accepting a meeting request

CSharp

MeetingRequest meetingRequest = MeetingRequest.Bind(service, new ItemId("abcd"));
meetingRequest.Accept(true /* sendResponse */);

Canceling a meeting

CSharp

Appointment appointment = Appointment.Bind(service, new ItemId("abcd"));
appointment.CancelMeeting();

Searching

The EWS Managed API exposes the full power of search. Once again, let's look at some examples.

Listing all the subfolders of the Inbox

CSharp

FindFoldersResults findResults = service.FindFolders(
    WellKnownFolderName.Inbox,
    new FolderView(int.MaxValue));

Finding the first ten items that are of high importance and have a subject that contains the word “API” in the Inbox

CSharp

ItemView view = new ItemView(10); // Return only ten items.
view.SearchFilter = new SearchFilter.SearchFilterCollection(
    LogicalOperator.And,
    new SearchFilter.IsEqualTo(ItemSchema.Importance, Importance.High),
    new SearchFilter.ContainsSubstring(ItemSchema.Subject, "API"));
FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Inbox, view);

Searching Folder objects

CSharp

Folder inbox = Folder.Bind(service, WellKnownFolderName.Inbox);
inbox.FindItems(view);

Creating a new search folder

CSharp

SearchFolder searchFolder = new SearchFolder(service);
searchFolder.DisplayName = "My search folder";
searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
searchFolder.SearchParameters.SearchFilter = new SearchFilter.SearchFilterCollection(
    LogicalOperator.And,
    new SearchFilter.IsEqualTo(ItemSchema.Importance, Importance.High),
    new SearchFilter.ContainsSubstring(ItemSchema.Subject, "API"));
searchFolder.Save(WellKnownFolderName.SearchFolders);

And Much More…

This article describes just a small subset of EWS Managed API features. Watch for posts on the Microsoft Exchange Team Blog or the Microsoft TechNet Forums: Development forum to learn more about the power of this new API.

Ready to Start?

The EWS Managed API beta is available now! Go download your copy from the Microsoft Download Center. To view the EWS Managed API beta documentation, see Exchange Web Services Managed API Reference.

We Want to Hear from You!

The Exchange Web Services team is eager to hear your feedback about the EWS Managed API. Please tell us about your experience and give us suggestions for improvement by posting to the Microsoft TechNet Forums: Development forum.