Exchange API-spotting : Exchange Web Services

Learn about the Exchange Web Services Managed API and how Exchange is getting “Cloud Ready” at PDC’08

JasonHen — Thu, 16 Oct 2008 00:23:00 GMT

Those of you who have already made plans to catch PDC ’08 in L.A. at the end of October be sure to catch the Exchange Web Services Managed API: Unified Communications Development for Exchange session. This exciting talk will be the coming out party for the managed API; it will be the first time that the API has been shown in public. We’ll have live coding, demo’s, and of course answer your questions on everything Exchange development. I’m looking forward to seeing you in L.A.!

Jason Henderson

Exchange Web Services Update Rollup 4 Roundup

JasonHen — Tue, 07 Oct 2008 22:32:00 GMT

We have just released update rollup 4 (RU4) for Exchange 2007 SP1. This rollup fixes some bugs in Exchange Web Services (EWS), and introduces some behavior changes to EWS to allow customers and partners the flexibility to accomplish some key scenarios. If you have written code against Exchange Web Services, we definitely recommend that you take a look at RU4. The following are the biggest changes that will be coming in the rollup:

- Item IDs are now returned after MoveItem/CopyItem calls.

- Unknown/unsupported item types are returned as Messages.

- Updating tasks can now have correct behavior for Start and Complete Date values.

ItemId of Item Is Returned After a MoveItem/CopyItem Call

Some of our observant developers have noticed that Exchange creates new destination item IDs for items when they are moved between folders. We created a place in the schema to return the destination ID of an item, and in the early stages of Exchange development, this ID was returned. We pulled it out late in the Exchange 2007 development cycle after we determined that the method of determining the destination ID was too resource-intensive. After consistent feedback from customers that this feature was needed so that items could be tracked as they were moved between folders, we implemented a much more performant solution. Now, if you call MoveItem/CopyItem, you’ll be able to identify the new item in the destination folder by looking at the destination ID that is returned by the MoveItem/CopyItem call.

Note: Cross-mailbox or mailbox-to-public folder CopyItem/MoveItem calls will not return destination IDs and RU4 must be applied to both the Client Access Server and the Mailbox Server Role for this feature to work.

Non-IPM.Note.* Items Are Returned as Messages

EWS in Exchange 2007 SP1 uses the <Item> type as the base class for items that are not strongly typed. This design has caused problems for customers who want to reply to item types that have a custom item class, or item types that EWS does not yet support, like IPM.Sharing or IPM.InfoPath. In RU4, all item types that we do not support natively in Exchange Web Services, like Journal, Sharing Requests, InfoPath forms, are returned as <Message> instead of <Item>. This means that you can see all the recipient information on the item, mark it as unread, reply to it, or forward it just like you would a normal item (assuming that the object supports forwarding/replying).

<Item> type still exists as a base class for <Message>, so most applications built on the auto-generated proxy classes will not be affected; however, applications that parse the XML directly could break if they are expecting <Item> rather than <Message>. To minimize the risk of breaking applications, this behavior is only applied when the Exchange2007_SP1 version header is specified.

We don’t take making changes in a rollup that could break applications lightly; our goal is to only change protocol behavior with the introduction of a new version header. However, we felt that this functionality is critical for some of our partners and customers, has a minimal impact on the majority of applications, is the way EWS should have worked in the first place, and can’t wait for the next service pack for Exchange, which could introduce a schema change for a new version header. For more details about this topic, see Robin’s June post that describes the proposed change and asks for feedback.

Updating Recurring Tasks Now Works Correctly

In Exchange 2007 and Exchange 2007 SP1, when a task is updated, such as by marking CompleteDate, the Client Access server shifts the date specified as the complete date according to the offset of its time zone. This is bad because clients are rarely aware of the time zone that the server is operating in. If the Client Access server and the client time zones are far enough apart, tasks could be marked as completed on the wrong day — not good!

The problem is that no time zone information is passed to EWS in tasks, yet a time zone is required when saving/updating/getting tasks to make sure that the task is marked as completed on the correct day. To fix this problem, with RU4, EWS can treat offset date times in a special way when they are the Complete Date, Due Date, or Start Date elements of a task. The offset, for example 10:00:00T-08:00, is used to create a time zone for that offset. This time zone is used when the task is saved so that the date the task was completed is always the date intended.

This post only covers the changes in RU4 that we think are most interesting to Exchange Web Services developers. We will be posting this and additional information in KB articles shortly. We hope you find this information useful and as always appreciate your feedback.

Jason Henderson and Andrew Salamatov

New and improved - We updated the TechReady 2007 Talk article download

Ray Dixon — Wed, 25 Jul 2007 20:52:49 GMT

If you downloaded the code samples for the Exchange Server Developer Center article TechReady 2007 Talk: Developing With Exchange Web Services, you probably had some problems building the projects, because some of the files didn't make it into the download packages.

We've corrected that and the updated download packages now contain all the files you need to successfully build the projects. We also updated the Readme file with instructions about how to replace the reference to the Exchange Web Services end point, so the projects use your Exchange Web Services installation.

You can find both the English (TechReady2007EWS-en.exe) and French (TechReady2007EWS-fr.exe) download packages on the TechReady 2007 Exchange Web Services Samples download page.

Using SQL Server Table-Valued User-defined Functions with Exchange Web Services

Thomr — Wed, 09 May 2007 01:41:33 GMT

A just-posted technical article by Jim Kleewein and Ray Dixon describes how to combine the SQL Server Tables and Exchange Web Services to access your Microsoft® Exchange Server 2007 Inbox data from Microsoft SQL Server™ 2005. This cool integration enables you to provide data from both Microsoft Exchange and SQL Server to client applications so that the data appears as if it were stored in SQL Server. As the article show, this creates some exciting development scenarios. You can find the article here.

Searching for your search folders?

JasonHen — Wed, 09 May 2007 01:04:00 GMT

Search folders in Exchange are a very powerful tool, but there is one quirk that often hangs developers up when they try to use them: “How do you create a search folder that can be seen in Outlook?”. Creating a search folder that is viewable in Outlook is important because it allows you to debug your search restriction and also allows you to present a search folder that an end user can interact with through Outlook or OWA.

The magic dust to creating a search folder that is viewable in Outlook is to make sure that you create it under the “Finder” folder which sits in the root of your mailbox heirarchy. If the folder is created anywhere else it will not be viewable in Outlook, though will contain the items that were specified in the query and can be access via EWS. The code below creates a search folder under the “Finder” folder which is referenced with the DistinguishedFolderIdNameType.searchfolders enumeration. The code below creates a search folder under the “Finder” folder and looks for all messages in your deleted items folder with “OOF” anywhere in a string in the subject. (For those of you that are wondering what an “OOF” is, it is what all we Microsofties call being “Out of Office”, supposedly the feature used to be called “Out of Facility”).

After this folder is created it will show up in Outlook online mode and OWA immediately, Outlook cached mode may take a bit longer to sync down the search folder, but it will eventually be populated as well.

ExchangeServiceBinding esb = new ExchangeServiceBinding();

esb.Url = "https://yoururl/ews/exchange.asmx";

esb.Credentials = CredentialCache.DefaultNetworkCredentials;

FolderIdType folderID = new FolderIdType();

//Now create the request that will create a new searchfolder under the finder directory

CreateFolderType folderType = new CreateFolderType();

SearchFolderType[] folderArray = new SearchFolderType[1];

folderArray[0] = new SearchFolderType();

folderArray[0].SearchParameters = new SearchParametersType();

folderArray[0].SearchParameters.Traversal = SearchFolderTraversalType.Shallow;

folderArray[0].SearchParameters.TraversalSpecified = true;

folderArray[0].SearchParameters.BaseFolderIds = new DistinguishedFolderIdType[1];

DistinguishedFolderIdType dType = new DistinguishedFolderIdType();

dType.Id = new DistinguishedFolderIdNameType();

dType.Id = DistinguishedFolderIdNameType.deleteditems; //search in the deleted items folder

folderArray[0].SearchParameters.BaseFolderIds[0] = dType;

PathToUnindexedFieldType path = new PathToUnindexedFieldType();

path.FieldURI = UnindexedFieldURIType.itemSubject; //search on subject

folderArray[0].SearchParameters.Restriction = new RestrictionType();

ContainsExpressionType expressionType = new ContainsExpressionType();

expressionType.Item = path;

expressionType.ContainmentMode = ContainmentModeType.Substring; //seach for substrings

expressionType.ContainmentModeSpecified = true;

expressionType.ContainmentComparison = ContainmentComparisonType.IgnoreCaseAndNonSpacingCharacters;

expressionType.Constant = new ConstantValueType();

expressionType.Constant.Value = "OOF"; //search for any string containing "OOF"

folderArray[0].SearchParameters.Restriction.Item = expressionType;

folderArray[0].DisplayName = "OOF Search"; //Name the searchfolder OOF Search

folderType.Folders = folderArray;

TargetFolderIdType targetFolder = new TargetFolderIdType();

//Create the searchfolder under the Finder Folder

DistinguishedFolderIdType searchFolder = new DistinguishedFolderIdType();

searchFolder.Id = DistinguishedFolderIdNameType.searchfolders;

targetFolder.Item = searchFolder;

folderType.ParentFolderId = targetFolder;

//Create the search folder

CreateFolderResponseType createFolderResponse = esb.CreateFolder(folderType);

//Return the ID of the newly created search folder

FolderInfoResponseMessageType folderInfo = (FolderInfoResponseMessageType)createFolderResponse.ResponseMessages.Items[0];

return folderInfo.Folders.Length == 0 ? null : folderInfo.Folders[0].FolderId;

When FindItem won't get what GetItem has!

Thomr — Tue, 01 May 2007 01:49:33 GMT

Okay, all you Exchange Web Services programmers out there. Since probably half of you have asked this question already, let me save the other half from half a day of half insanity trying to figure it out. The question in question? “Where the @#$($ is the message Body?”

When you’re using Exchange Web Services to retrieve messages from an Inbox, if you need to get the message Body or attachments, you need to use GetItem. Yeah, we know that FindItem would seem to get you there, especially with the AllProperties BaseShape. But, it doesn’t.

Check out the new Exchange Server Developer Center article, Finding the Message Body, for the full scoop on which properties GetItem and FindItem return. You’ll be glad you did.