Have you ever seen event 2917 in your Client Access server’s event log? It might look something like this:

Process w3wp.exe (PID=1234). A budget charge was encountered that exceeded the limit of '2.768900000' minutes.  Budget Owner: 'SomeUser', Component: 'EWS, CostType: 'CAS'.

Sounds scary, doesn’t it? The wording is a bit odd (feel free to blame me) and can lead one to assume that there is some strange throttling limit of 2.7689 minutes (or some other equally non-integer-like number) lurking inside Exchange. There is no such limit – that value indicates when the condition was discovered, not what the limit is. This is really more of a warning message, but is completely un-actionable and will be removed from a future release of the product. 

All this event is saying is that the throttling infrastructure noted that a given operation has taken longer than expected, and it wanted you to know about it. This could be the result of an overloaded mailbox server, intense periods of garbage collection, a domain controller issue, and so on… It does not suggest that the “budget owner” has done anything wrong or nefarious nor does it suggest that the user in question was throttled. You can ignore this event log and look forward to the days when it will no longer darken the doorstep of your event log.

David Sterling
Exchange Web Services
Inside Microsoft Exchange Server 2007 Web Services

When you use the FindItems method or the FindAppointments method in Exchange Web Services (EWS), it’s important to realize that neither of these methods returns all properties for the items returned by the query. For example, FindItems will not return the Body property for a message item, and FindAppointments will not return the RequiredAttendees property for a calendar item. Therefore, if you are interested in additional properties that cannot be returned by FindItems or FindAppointments, you must explicitly load the additional properties to the items that are returned by the query.

Fortunately, the EWS Managed API provides an easy way to load additional properties for multiple items with a single call to EWS. The following code example shows you how to search the Inbox folder for items that match the specified search criteria, and then use the LoadPropertiesForItems method to load the Subject property and Body property for the items returned by FindItems.

// Specify the IdOnly response shape, and specify that
// FindItem results should be requested in batches of 25.
ItemView view = new ItemView(25);
view.PropertySet = new PropertySet(BasePropertySet.IdOnly);
view.Offset = 0;
view.OffsetBasePoint = OffsetBasePoint.Beginning;

// Specify search criteria.
SearchFilter searchFilter = new SearchFilter.ContainsSubstring(ItemSchema.Subject, "Message #");

// Declare findResults.
FindItemsResults<Item> findResults;

do
{
    // Call FindItems to search the Inbox folder.
    findResults = service.FindItems(WellKnownFolderName.Inbox, searchFilter, view);

    // Load additional properties for the current batch of items.
    service.LoadPropertiesForItems(findResults, new PropertySet(ItemSchema.Subject, ItemSchema.Body));

    // TODO: Process the current batch of items.

    // If more items are available, update the offset value so that the next
    // batch of items is returned by the next call to FindItems.
    if (findResults.NextPageOffset.HasValue)
    {
        view.Offset = findResults.NextPageOffset.Value;
    }
}
while (findResults.MoreAvailable);

Note: By specifying a page size of 25 when ItemView is instantiated, this example requests FindItems results (and subsequently calls LoadPropertiesForItems) for a maximum of 25 items at a time. Processing items in batches like this is helpful in that it reduces the likelihood that the server will be overloaded when the number of search results is large.

The following is the XML response that is returned by from FindItems in the above code example. A total of five messages that match the search criteria were found in the Inbox folder. Item identifiers and change keys have been shortened for readability.

<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <m:FindItemResponse
                xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
                xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
        <m:ResponseMessages>
            <m:FindItemResponseMessage ResponseClass="Success">
                <m:ResponseCode>NoError</m:ResponseCode>
                <m:RootFolder IndexedPagingOffset="5" TotalItemsInView="5" IncludesLastItemInRange="true">
                    <t:Items>
                        <t:Message>
                            <t:ItemId Id="AAT5QA=" ChangeKey="CQAAA" />
                        </t:Message>
                        <t:Message>
                            <t:ItemId Id="AAT5QB=" ChangeKey="CQAAB" />
                        </t:Message>
                        <t:Message>
                            <t:ItemId Id="AAT5QC=" ChangeKey="CQAAC" />
                        </t:Message>
                        <t:Message>
                            <t:ItemId Id="AAT5QD=" ChangeKey="CQAAD" />
                        </t:Message>
                        <t:Message>
                            <t:ItemId Id="AAT5QE=" ChangeKey="CQAAE" />                         
                        </t:Message>
                    </t:Items>
                </m:RootFolder>
            </m:FindItemResponseMessage>
        </m:ResponseMessages>
    </m:FindItemResponse>
</s:Body>

Note: In this example, the number of items that matched the specified search criteria was fewer than our specified paging size of 25; therefore, all items were returned by the first call to FindItems. If more than 25 items (the specified paging size) had matched the specified search criteria, FindItems (and LoadPropertiesForItems) would have executed multiple times — once for each batch of 25 items that matched the specified search criteria.

The following is the XML request that is generated by calling LoadPropertiesForItems in the above code example. As this XML request shows, LoadPropertiesForItems translates to a batch GetItem call under the covers — the Subject and Body property for all five items in findResults are requested in a single call GetItem call to EWS.

<m:GetItem>
    <m:ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
            <t:FieldURI FieldURI="item:Subject" />
            <t:FieldURI FieldURI="item:Body" />
        </t:AdditionalProperties>
    </m:ItemShape>
    <m:ItemIds>
        <t:ItemId Id="AAT5QA=" ChangeKey="CQAAA" />
        <t:ItemId Id="AAT5QB=" ChangeKey="CQAAB" />
        <t:ItemId Id="AAT5QC=" ChangeKey="CQAAC" />
        <t:ItemId Id="AAT5QD=" ChangeKey="CQAAD" />
        <t:ItemId Id="AAT5QE=" ChangeKey="CQAAE" />
    </m:ItemIds>
</m:GetItem>

Now, you might assume that the same simple call to LoadPropertiesForItems can also be used to load properties for calendar items that are returned by FindAppointments. And it will work, with one small caveat: LoadPropertiesForItems takes an argument of type IEnumerable<Item>, whereas FindAppointments returns IEnumerable<Appointment> — so you must find a way to pass the results from FindAppointments to LoadPropertiesForItems as IEnumerable<Item>. Fortunately, this is easily accomplished by using Linq. The following code example shows you how search the Calendar folder for appointments that match the specified search criteria, and then use the LoadPropertiesForItems method to load the Subject property, the RequiredAttendees property, and the OptionalAttendees property for the calendar items returned by FindAppointments.

// Define search parameters and maximum number of items to return.
CalendarView calView = new CalendarView(DateTime.Now, DateTime.Now.AddDays(3), 25);

// Specify the IdOnly shape.
PropertySet props = new PropertySet(BasePropertySet.IdOnly);
calView.PropertySet = props;

// Call FindAppointments to search the Calendar folder.
FindItemsResults<Appointment> findResults = service.FindAppointments(WellKnownFolderName.Calendar, calView);

if (findResults.TotalCount > iMaxItemsReturned)
{
    string sMsg = "Total number of items that match search criteria exceeds specified maximum number of results to return.";
    sMsg += " To find all items that match the specified search criteria, either narrow the date range ";
    sMsg += "or increase the specified maximum number of items to return in CalendarView.";
    Exception e = new Exception(sMsg);
    throw e;
}
else
{
    // Call LoadPropertiesForItems to load the Subject, RequiredAttendees, and OptionalAttendees properties.
    service.LoadPropertiesForItems(from Item item in findResults select item,
                new PropertySet(BasePropertySet.IdOnly,
                        AppointmentSchema.Subject,
                        AppointmentSchema.RequiredAttendees,
                        AppointmentSchema.OptionalAttendees));
}

Note: To use Linq as shown in the above example, you must include the following directive in your program: using System.Linq;

Want to learn more about working with the EWS Managed API? Check out the code examples that are available in the Working with the EWS Managed API section of the Microsoft Exchange Web Services Managed API 1.0 SDK.

When studying the event log over a steaming hot cup of coffee, have you ever seen the following directory event (2914)?

Process w3wp.exe (UNKNOWN) (PID=15780). Deleted throttling policy was referenced.  Id: 'Org: SomeOrg…/Configuration, Id: CN=ThrottlingPolicy-DefaultMailboxPlan\0ADEL:4d73d344-d66f-4eed-85f9-b6c95dcd2a13,CN=Deleted Objects,CN=Configuration,DC=…,DC=com'.

This one does require some action. In the case of this event log, a throttling policy was deleted from Active Directory, but because *someone* did not use Remove-ThrottlingPolicy to do so, the links from the associated mailboxes did not get updated properly. The fix is relatively easy – you just need to reassign the affected mailboxes to a valid throttling policy. Now, I highlighted the “\0ADEL” wording in the event log for a reason. That is a very reliable way to determine whether we are dealing with a deleted object in Active Directory. We can use that to our advantage in the Exchange Management Shell.

[PS] D:\Windows\system32>get-mailbox | ? {$_.ThrottlingPolicy -ilike "*`nDEL*"} | fl Name, ThrottlingPolicy

Name             : JohnDoe
ThrottlingPolicy : SomeDomain/Configuration/Deleted Objects/SomePolicy
                   DEL:3fb98144-b317-413b-9a19-78003fd5a633

The key is in the “*`nDEL*” string.  The value “`n” is the Exchange Management Shell’s way of escaping the new-line sequence.

Now that we have discovered the mailbox that is having the issue, we can assign that mailbox to another policy. In my case, I just want JohnDoe to use the default policy, so I will just null out the ThrottlingPolicy parameter.

get-mailbox | ? {$_.ThrottlingPolicy -ilike "*`nDEL*"} | set-Mailbox –ThrottlingPolicy $null

Even with this problem present, the throttling policy framework was behaving properly and “falling back” to the default throttling policy governing John Doe. However, it is a good idea to clean up these issues in the directory if you encounter them and make your throttling policy association links explicit rather than relying on the fallback logic to do the “right thing”.

David Sterling
Exchange Web Services
Inside Microsoft Exchange Server 2007 Web Services

We’re excited to announce that we have released updates to the Exchange 2010 SDKs for Microsoft Exchange Server 2010 Service Pack 1 (SP1). Exchange 2010 SP1 introduces many new programmability features that will help you create robust applications. Here is an overview of what has changed for Exchange programmability documentation for this release:

· Exchange 2010 SP1 Beta Web Services SDK – We added documentation in support of the many new features for Exchange Web Services. This includes a new EmptyFolder operation to simplify the deletion of folder content, bulk transfer to support the import/export of information in a mailbox, conversation operations to help manage items in a conversation, and the Inbox rules operations to enable you to programmatically use Inbox rules. We have also made small changes to existing API features

· Exchange 2010 SP1 Beta Transport Agents SDK & Exchange 2010 SP1 Beta Outlook Web App Customization SDK – We have included new documentation for new types and members that were added to the APIs, and updates to existing types and members.

· Exchange 2010 SP1 Beta Backup and Restore SDK – We updated information about running consistency checks on databases in a Database Availability Group (DAG).

Check out the What’s New pages for the SDKs for more details about the exciting changes to your favorite Exchange API.

We hope the new features and documentation help you achieve your organizational goals for Exchange connectivity and interoperability. And while you are reading this, if you’d like to provide input for future Exchange programmability features and improvements, submit your feedback to our very own David Claux on the Exchange Server Development forum.

Happy coding!

Michael Mainer

How to use CHKSGFILES multi-threaded for faster consistency checks

One of the questions that we sometimes get here, and that we’ve never really been able to answer is: do I HAVE to run the database consistency check (the CHKSGFILES API) in single-threaded fashion? Doing things multi-threaded could be so much faster! Well the answer is some parts no, but some parts yes.

If you don’t already know, CHKSGFILES is used by applications that back up Exchange databases, to ensure that the database to be stored is actually in good health and not corrupted. With Exchange 2010, it’s much less likely there will be a corruption problem, but it's safer for your backup and restore application to verify the data before making the backup.

Well, after some extensive archeology, we’ve determined that, if you do it right, you actually CAN run parts of CHKSGFILES multi-threaded. We’ll be adding this information into the SDK for October 2010, but wanted to get the word out now for those of you who are interested.

The general, using CHKSGFILES to check database consistency in a multi-threaded application runs like in the following example. Remember, this is just an EXAMPLE, and is only intended to show which parts of CHKSGFILES must be handled in what way.

This example application uses two main processes, and a set of worker threads. The first (orange) process handles the overall backup job, while the second (blue) handles queue requests by creating worker threads to verify the database pages and log files. Central to the system is a request and completion-status queue.

Backup job-engine (the single-threaded part)

The Backup Job-engine process block (orange) in the diagram indicates the parts of the database consistency check that must be run single-threaded.

IMPORTANT Your application must never allow more than one Backup Job-engine block to operate at the same time. The CHKSGFILES APIs shown in that block should never be called in parallel. Your application should ONLY call CHKSGFILES consistency checks in sequence. The CHKSGFILES DLL does not support out-of-sequence or simultaneous calls to New(), ErrInit(), ErrCheckDbHeaders(), ErrTerm() and Delete(). Your application should call those APIs only once for each consistency check. After the sequence shown in the Backup Job-engine block has been completed, only then can that sequence be restarted.

When the Backup Job-engine section starts, it should initialize whatever request queuing mechanism is being used. In this example, it’s a queue that includes the requests, the return status of those requests, and a separate process that scans for entries in the request queue. Because the intention of running a database consistency checks is to find errors, the queue needs to return that success / failure information to the main part of the program.

After the queue is initialized, the backup job can use Windows VSS to take the snapshot. After the snapshot is successfully made and available, the backup application can call the CHKSGFILES New() function to obtain an instance of the API. The backup job must then call ErrInit(), indicating which databases are to be checked, the log-file path, and other parameters.

Then the backup job process calls the ErrCheckDbHeaders() function, to verify that all the databases have the proper header information. It is very important that ErrCheckDbHeaders() be called only once to check ALL the databases that were specified in ErrInit(). For Exchange 2007, this will likely be all the databases in a storage groups. For Exchange 2010, this will probably be only a single database, because ErrInit() accepts only a single log file path.

In this example, the single-threaded Backup Job-engine then adds requests into the queue for the database pages in each database, and a single request to check the log files.

In this example, the backup job-engine then waits until the request queue contains completion status for all the requests. Then the backup job-engine calls the ErrTerm() function. Like ErrCheckDbHeaders(), your application must call ErrTerm() only once. It is up to the application to ensure that it has tried to check all the database pages and log files. Do not try to use ErrTerm() to keep track of the progress: if you call ErrTerm() and all the pages and logs have not been checked, it will return an error and invalidate all checks that had been done on those databases. In this example, the backup job-engine process uses the queue entries to keep track of which database pages have been checked.

Finally, the backup job engine can call the Delete() function, to dispose of the CHKSGFILES instance. Then, based on the results, the backup application can copy the snapshot contents to the backup media, and continue processing the backup job.

Implication of storage groups

At this point a short discussion about the parameters passed to ErrInit() is appropriate. In Exchange 2007, when CHKSGFILES was introduced, the Exchange storage architecture includes Storage Groups, which are collections of databases that can be managed together as a unit. So, with Exchange 2007 servers, you will probably pass a list of the databases in a storage group to the ErrInit() function. But, Exchange 2010 doesn’t have storage groups. Indeed, typically each database and log file set is kept separate. So, for checking Exchange 2010 databases, you will very likely pass a single-element array with one database and log file path to ErrInit(). Remember, ErrInit() requires the databases to be specified in an array, even when there is only one database to be checked.

You might wonder: if the application typically only sends a single database through the CHKSGFILES APIs at a time, what good is multi-threading? Good question! For that individual database, the page checks can be run in parallel, which will certainly speed up the process. But if you need to check multiple Exchange 2010 databases, your application will need to separately call New() and ErrInit() for each database, and separately handle the different instances of the CHKSGFILES API. Just like with a single set of databases sent to ErrInit(), the single-threading and sequencing rules for the API have to be followed for each instance.

Queue Servicing process (the multi-threaded part)

As you can tell, nearly the whole CHKSGFILES API needs to be run in a single thread, and there can be no out-of-sequence calls made. In the example application, the CHKSGFILES parts that can be run multi-threaded are shown as the Queue Servicing process (blue), and the Database Page and log file worker threads (green).

IMPORTANT The CHKSGFILES API does support checking the log files [using the ErrCheckLogs() API] parallel to checking the database pages [using the ErrCheckDbPages() API]. However, your application must call ErrCheckLogs() only ONCE for each set of databases that were passed to ErrInit(). If ErrCheckLogs() is called more than once, an error will be returned, and the entire consistency check will have failed, even if no actual database or log file errors exist.

When the queue servicing process starts, it begins checking for new entries in the request queue. When it sees a new request, it can start a new worker thread to service that request.

When it starts, the worker thread (green) should obtain the request information from the queue (or directly from the request queue servicing process), and then perform the check. In this example application, it is up to the worker thread to process the request appropriately: database page requests use ErrCheckDbPages(), while log file requests use ErrCheckLogs(). If the backup job-engine process is running properly, there should never be more than one request for log file checks for each set of databases passed to ErrInit(). When the check has completed, the worker thread should update the request status information in the queue, and then the thread should exit.

When all the dispatched threads have exited, the queue processing service can signal the backup job-engine process via the queue. Alternatively, the backup job-engine process can detect when there are no more unprocessed requests in the queue.

So, that’s all there is. It’s not terribly complicated, but your application must follow these rules:

• CHKSGFILES New(), ErrInit(), ErrCheckDbHeaders(), ErrTerm() and Delete() can only be called from a single thread, and must be called in the proper sequence, and can only be called once.
• CHKSGFILES ErrCheckDbPages() and ErrCheckLogs() can be called in a multi-threaded manner, but only after ErrCheckDbHeaders() is called and before ErrTerm() is called.
• CHKSGFILES ErrCheckLogs() must only be called once for all the databases specified to ErrInit(). But, ErrCheckLogs() can be called in parallel with calls to ErrCheckDbPages().
• If you’re backing up multiple Exchange 2010 databases, you must obtain separate CHKSGFILES instances for each database, and the sequencing and concurrency rules still apply for each instance.

Using a combination of single- and multi-threading, and obeying the rules described in this blog post, your backup application can more quickly check Exchange databases than in a purely single-threaded manner.

Thom Randolph

Documentation Manager

Exchange Developer Documentation

Microsoft Corporation

The Exchange Developer Documentation Team is happy to announce the October 2010 release of the Exchange Server 2010 Service Pack 1 (SP1) SDKs. If you’ve been keeping up with our SDK releases, then you know that we already released a lot of new information about Exchange 2010 SP1 back in June. The updates for October cover the released version of SP1, with additional information and updates to the preliminary release. Check out the What’s New topics for these SDKs to get more details:

• Exchange 2010 SP1 Web Services SDK
• Exchange 2010 SP1 Transport Agents SDK
• Exchange 2010 SP1 Outlook Web App Customization SDK
• Exchange 2010 SP1 Backup and Restore SDK

The Exchange 2010 Management Shell SDK will be released in the near future as well; for now, you can still check out the June release, which includes preliminary information about SP1. The Exchange Web Services Managed API 1.1 SDK is also available with updates for October, and includes several new conceptual topics that include more information about how to use this API.

We hope the release of the documentation help you achieve your organizational goals for Exchange connectivity and interoperability.

Bob Bunn
Microsoft Corporation

We know you’ve been waiting to see the new Exchange Web Services features in Exchange 2010 SP1 exposed in the EWS Managed API, and I’m here to tell you that your wait is over. The Exchange Web Services Managed API 1.1 is now available for download. The EWS Managed API 1.1 exposes the following features that were introduced in Exchange 2010 SP1:

· Archive mailbox – Access to archive folders and items. Everything you can do with mailbox items and folders is available for your archived information. Equal access for all items and folders!

· Conversations – Emails are social and so is your application, so try the new Conversations feature exposed by EWS to easily manage email conversations.

· Inbox Rules – Would you like to tell your Exchange server where to store it (emails)? Server-side Inbox rules are now available as a programmatic interface for your Exchange client applications. For more information, see Working with Inbox Rules.

· Streaming Notifications – Want your cake and eat it too? Now you can with streaming notifications. Streaming notifications provide you with the benefits of both push and pull event notification models.

For a convenient chart that lists applicable features by server and API versions, see Introduction to the EWS Managed API.

And before I forget, make sure you visit the important companion to the EWS Managed API 1.1, the Exchange Web Services Managed API 1.1 SDK.

It’s time to rev your application!

Michael Mainer
Exchange SDK and Interoperability
Microsoft Corporation

Hi Everyone,

I’m pleased to announce the public availability of the Microsoft Exchange Web Services (EWS) Java API 1.1. The final package was posted this past weekend for download. This package offers the same functionality that our EWS Managed API 1.1 for the Microsoft .NET Framework offers.  During the course of development, we’ve had internal and external users working with beta drops of this API.  There is a lot of excitement about it, and now we’re happy to finally offer it to everyone.

This API was developed in order to facilitate Exchange development on other platforms. It has been over a year in development, and it is our first release of a package that includes source code. Although the source is viewable, our licensing for this iteration does not allow for modification of the source code. It can be used to build against a particular JRE or JDK, but the license agreement only allows the object code to be shared in your application. We took this approach because we’re keeping the releases in sync with our Exchange versions. The 1.1 release corresponds to Exchange 2010 SP1. 

We’re looking forward to what the future holds for client development on other platforms. 

We encourage you to develop your Exchange client on other platforms now, and would like to hear about your projects.

Michael Mainer
Exchange SDK and Interoperability
Microsoft Corporation

Microsoft Exchange Server 2010 Service Pack 1 (SP1) introduces streaming notifications, a new feature that combines push and pull notifications. For those of you who are not too familiar with notifications, I’ll give some background information. Pull notifications require your application to create a subscription and every now and then request an update from the server. This can create quite a bit of traffic between the client and server if you want to keep up-to-date with events on the server. Push notifications require you to write your own listener application. You create a push subscription with the server and when an event fires, it pushes the notification to your listener application. This works well because you don’t have to keep asking the server for updates, but it does require that you create a separate application to receive the notifications. Now, we have the best of both worlds with streaming notifications. After you have established your notification subscription, the connection remains open to allow the server to push notifications back to your application. You don’t have to request updates as for the pull subscription, and you don’t have to create a listener application as for the push notifications.

We wrote a console example for creating the subscription and handling notification responses. The first step in your application is to create a service binding to your Exchange mailbox. Because this is a pretty common routine in Microsoft Exchange Web Services (EWS) Managed API, I don’t want to go over it in detail here, but if you need a refresher check out the topic Connecting to EWS in the EWS Managed API SDK.

After the service binding is completed, call the SetStreamingNotifications function and pass in the service binding. In this example, a subscription is made to the Inbox and the notifications will be sent for new e-mail messages and for items that have been created or deleted in the Inbox. Because this is just an example, the timeout is set to one minute, but you can adjust this as necessary for your application. This example will also recognize the OnDisconnect event and ask if the connection should remain open. You can see that after the subscription is created, it’s very easy to reopen the connection. If you don’t want to reopen the connection, the code will close the connection object.

When a notification is sent back, the OnEvent function is called and a message is output to the console. When you get the notification, you also get the itemID that you can use to bind to the item and get additional information about that item.

The following code shows the console application…

static void SetStreamingNotifications(ExchangeService service)
{
    // Subscribe to streaming notifications on the Inbox folder, and listen
    // for "NewMail", "Created", and "Deleted" events.
    StreamingSubscription streamingsubscription = service.SubscribeToStreamingNotifications(
        new FolderId[] { WellKnownFolderName.Inbox },
        EventType.NewMail,
        EventType.Created,
        EventType.Deleted);

    StreamingSubscriptionConnection connection = new StreamingSubscriptionConnection(service, 1);

    connection.AddSubscription(streamingsubscription);
    // Delegate event handlers.
    connection.OnNotificationEvent +=
        new StreamingSubscriptionConnection.NotificationEventDelegate(OnEvent);
    connection.OnSubscriptionError +=
        new StreamingSubscriptionConnection.SubscriptionErrorDelegate(OnError);
    connection.OnDisconnect +=
        new StreamingSubscriptionConnection.SubscriptionErrorDelegate(OnDisconnect);
    connection.Open();

    Console.WriteLine("--------- StreamSubscription event -------");
}

static private void OnDisconnect(object sender, SubscriptionErrorEventArgs args)
{
    // Cast the sender as a StreamingSubscriptionConnection object.          
    StreamingSubscriptionConnection connection = (StreamingSubscriptionConnection)sender;
    // Ask the user if they want to reconnect or close the subscription.
    ConsoleKeyInfo cki;
    Console.WriteLine("The connection to the subscription is disconnected.");
    Console.WriteLine("Do you want to reconnect to the subscription? Y/N");
    while (true)
    {
        cki = Console.ReadKey(true);
        {
            if (cki.Key == ConsoleKey.Y)
            {
                connection.Open();
                Console.WriteLine("Connection open.");
                break;
            }
            else if (cki.Key == ConsoleKey.N)
            {
                // The ReadKey in the Main() consumes the E.
                Console.WriteLine("\n\nPress E to exit");
                break;
            }
        }
    }
}

static void OnEvent(object sender, NotificationEventArgs args)
{
    StreamingSubscription subscription = args.Subscription;

    // Loop through all item-related events.
    foreach (NotificationEvent notification in args.Events)
    {

        switch (notification.EventType)
        {
            case EventType.NewMail:
                Console.WriteLine("\n-------------Mail created:-------------");
                break;
            case EventType.Created:
                Console.WriteLine("\n-------------Item or folder created:-------------");
                break;
            case EventType.Deleted:
                Console.WriteLine("\n-------------Item or folder deleted:-------------");
                break;
        }
        // Display the notification identifier.
        if (notification is ItemEvent)
        {
            // The NotificationEvent for an e-mail message is an ItemEvent.
            ItemEvent itemEvent = (ItemEvent)notification;
            Console.WriteLine("\nItemId: " + itemEvent.ItemId.UniqueId);
        }
        else
        {
            // The NotificationEvent for a folder is an FolderEvent.
            FolderEvent folderEvent = (FolderEvent)notification;
            Console.WriteLine("\nFolderId: " + folderEvent.FolderId.UniqueId);
        }
    }
}
static void OnError(object sender, SubscriptionErrorEventArgs args)
{
    // Handle error conditions.
    Exception e = args.Exception;
    Console.WriteLine("\n-------------Error ---" + e.Message + "-------------");
}

To make this application work properly, bind it to your Exchange mailbox and call the SetStreamingNotifications function. Then send a message to this mailbox from an e-mail client of your choice — just do it before the one minute timeout occurs. You will then get a message that an item was created and you have a new e-mail message in your Inbox.

The Exchange Interoperability Team is excited to announce the initial release of the Microsoft Exchange RPC Extractor (RPX). RPX is a command-line tool that can parse network captures and interpret remote procedure calls (RPCs) made from a client to Microsoft Exchange Server. RPX uses the information provided in the Microsoft Exchange Server protocol documentation to parse RPCs, remote operations (ROPs) and the parameters for each ROP.

The goal for RPX is to assist developers who are implementing the Microsoft Exchange protocols by allowing them to view and compare the RPC traffic between clients and servers. Network capture files are transformed into text files that detail RPC requests and responses, including parameters and return codes.

If you are working with the Microsoft Exchange protocols, follow the link below to download RPX today and try it out!

Microsoft Exchange RPC Extractor 1.0

Interested in learning more about the Exchange Server RPC protocols? The Exchange Server Interoperability team is pleased to announce that presentations from the Exchange RPC Protocols Plugfest event (January 2011) are now available on Channel 9. Plugfest events are part of the Microsoft Open Specifications Program which helps developers create solutions by providing open access to technical specifications and support through a variety of channels.

If you’re working with the Microsoft Exchange protocols, check out the Exchange RPC Protocols Plugfest January 2011 series on Channel 9 for valuable information about the following topics:

• Exchange Fast Transfer and Incremental Change Synchronization ([MS-OXCFXICS])
• Exchange RPC and ROPs ([MS-OXCROPS])
• Exchange Protocol Test Suite Architecture
• Exchange Protocol Objects and Properties ([MS-OXCPRPT])

Kim Brandl
Exchange Interoperability
Microsoft Corporation

Microsoft Exchange Online as part of Microsoft Office 365 provides many of the same app-development capabilities that are available for Microsoft Exchange Server running on-site. The Exchange Developer Documentation team is pleased to announce the release of a new Exchange Online Developer Center page that will be your portal for information about Exchange Online development.

If you’re not quite up to the rock-star level as an Exchange programmer, or if Exchange Online is the only flavor of Exchange you’ve ever known, this is the place for you! And even if you’re already an experienced Exchange developer, we want to make it really easy to use that Exchange knowledge as you create apps for the Cloud.

Along with the new Exchange Online page, we have an article to help you get started writing apps that use Exchange Web Services (EWS) and EWS Managed API. This article explains the important first steps to get things running smoothly and quickly.

We have more articles coming in the near future, including one about configuring and using Exchange Autodiscover, so come back to the site often to find new information. We plan to provide great information for programming with Exchange Online for all types of developers, from experienced corporate and ISV developers to total newbies.

A bunch of articles, of course, can’t tell the whole story. As the Office 365 Beta progresses, and as the service officially becomes available, we’ll continue posting articles, blog posts, podcasts, and even videos. Because we know you’ll have questions, the writing team will also be helping out in the forums.

We look forward to hearing from you more than ever, and to helping your Exchange development projects succeed.

Best regards to our new and current readers,

Thom Randolph
Exchange Developer Documentation
Microsoft Corporation

We are pleased to announce the availability of the Microsoft Office 2010 Developer Map. Whether you are new to developing with Microsoft Exchange, or a seasoned veteran, this map will guide you through the tools, applications, platforms, and services you can use to develop your application. The interactive map is a living document that provides links to MSDN Library documentation. You can also download the poster and print it out to hang on your wall.

Start visualizing the applications, services like Exchange Online, client/server data-access technologies like Exchange Web Services, on-premise servers, platform products and technologies, and tools that can help you build multiple line-of-business solutions. 

• Interactive map: http://msdn.microsoft.com/office2010devmap
• Poster download: http://www.microsoft.com/downloads/en/details.aspx?FamilyID=e92d8703-342e-4bd6-8877-d22b888ff29b

Bob Bunn
Exchange Developer Documentation
Microsoft Corporation

We are specifically focused on throttling of Exchange Web Services (EWS) and MAPI with RPC over HTTP (as used by Microsoft Outlook) and with hard limits set by the Exchange Online system. Any mention of specific setting values were obtained for the service version 14.0.100.0. You will want to have your tenant admin obtain and confirm setting values.

Note   An on-premise Microsoft Exchange deployment may have a different throttling policy. Administrators can modify throttling settings for Microsoft Exchange on-premises. Administrators cannot configure throttling policies for Exchange Online.

What is the impact of exceeding throttling budgets?

Exchange throttling is based on the amount of Active Directory, Exchange store, and other resources a client consumes. A budget is allocated to each client to limit the resources a particular user consumes. This budget is recharged every minute.

EWS clients can exceed their budgets by sending too many concurrent requests, or by requesting too many resources on the server. When this occurs, additional requests are queued until one of two things happen:

• The application is under budget. The request is then processed and the client experiences an increase in latency.
• The request has been queued for more than 60 seconds, after which time the server sends an error response to the application.

When MAPI clients exceed their budgets, additional requests are returned with an error, until the application is under budget. There is no queuing of requests.

How do I get throttling settings?

Tenant administrators can view throttling settings by using Remote PowerShell and the Get-ThrottlingPolicy cmdlet. For information about how to connect Remote PowerShell for your tenant, see Install and Configure Windows PowerShell and Connect Windows PowerShell to the Service on Microsoft TechNet.

Use the Get-ThrottlingPolicy cmdlet (without arguments) to get all the throttling policy settings. Throttling policies might change to enhance service performance, so you should confirm throttling policies. We suggest that you make your client applications configurable to adjust for potential changes in throttling policy for Exchange Online. Additionally, because Exchange Online and Exchange on-premises might have different throttling policies, you may want to account for this when you design your client applications.

What are the common throttling settings?

The following throttling settings are common to both EWS and MAPI (RPC over HTTP) clients:

• MessageRateLimit – Identifies the maximum number of messages that can be sent per minute. This is configured to count sent messages on a per IP address basis.
• RecipientRateLimit – Identifies the maximum number of recipients that a sender can send to in a 24-hour period.
• ForwardeeLimit – Identifies the maximum number of recipients that can be configured for Inbox rules when the user account is using the forward or redirect action.

What are the MAPI with RPC over HTTP throttling settings?

The prefix RCA in the MAPI RPC/HTTP settings represents RPC Client Access. The following throttling settings are specific to MAPI RPC over HTTP:

• RCAMaxConcurrency – Identifies the maximum number of concurrent connections that can be maintained by MAPI RPC/HTTP clients (such as Microsoft Outlook) at any one time. Attempts to open more than the maximum number of connections will fail. Existing connections will remain unaffected. Active Directory calls count toward the number of concurrent connections. 
• RCAPercentTimeInAD – Identifies the maximum amount of time that can be spent by a Client Access server when accessing Active Directory resources on behalf of a client, per minute. This budget is calculated by dividing the throttling value for this setting by 100 and then multiplying the result by 60 seconds. For example, an RCAPercentTimeInAD throttling value of 5 results in a throttling threshold of 3 seconds (5/100 * 60 seconds).
• RCAPercentTimeInCAS – Identifies how much time all concurrent MAPI RPC/HTTP connections can consume on the Client Access server per minute. This is calculated on a per user basis. This budget is calculated by dividing the throttling value for this setting by 100 and then multiplying the results by 60 seconds. For example, an RCAPercentTimeInCAS throttling value of 205 results in a throttling threshold of 123 seconds (205/100 * 60 seconds). If the setting is 123 seconds, two concurrent MAPI RPC/HTTP connections can be open on a Client Access server for a full 60 seconds, thus using up 120 seconds per minute. A third connection can only use the remaining 3 seconds per minute, assuming all three connections occur concurrently and are initiated at the same time. 
• RCAPercentTImeInMailboxRPC – Identifies how much time all concurrent MAPI RPC/HTTP connections can consume for accessing the mailbox per minute. This budget is calculated by dividing the throttling value for this setting by 100 and then multiplying the results by 60 seconds. For example, an RCAPercentTimeInMailboxRPC throttling value of 200 results in a throttling threshold of 120 seconds (200/100 * 60 seconds). This means that two connections can consume 60 seconds per minute (120 seconds total per minute) as long as there are no other connections.

What are the Exchange Web Services throttling settings?

The following throttling settings are specific to Exchange Web Services:

• EWSFastSearchTimeoutInSeconds – Identifies how long an Exchange Search (indexed search) request will continue until it times out.
• EWSFindCountLimit – Identifies the maximum number of search results in concurrent requests. For more information, see Throttling Policies and the EWS FindCountLimit. We suggest that searches all be paged and that the page size not exceed 1000 results.
• EWSMaxConcurrency – Identifies the maximum number of concurrent connections that can be maintained by EWS clients at any one time. Attempts to open more than the maximum number of connections will fail. Existing connections will remain unaffected. Active Directory calls count toward the number of concurrent connections. 
• EWSMaxSubscriptions – Identifies the maximum number of push, pull, or streaming notification subscriptions. If a server has too many notification subscriptions, it will start returning server busy errors. The server starts to return errors when the number of open connections reaches approximately 20 for a user. The charges for EWSMaxSubscription are calculated as follows:
  • Client – charged against the caller, also called the mailbox owner.
  • Intra-forest ExchangeImpersonation – charged against the caller.
  • Server-to-Server – charged against the underlying effective caller.
• EWSPercentTimeInAD – Identifies the maximum amount of time that can be spent by a Client Access server when accessing Active Directory resources on behalf of a client account, per minute. This budget is calculated by dividing the throttling value for this setting by 100 and then multiplying the result by 60 seconds. For example, a EWSPercentTimeInAD throttling value of 50 results in a throttling threshold of 30 seconds (50/100 * 60 seconds).
• EWSPercentTimeInCAS – Identifies how much time all concurrent EWS connections can consume on the Client Access server per minute. This is calculated on a per user basis. This budget is calculated by dividing the throttling value for this setting by 100 and then multiplying the results by 60 seconds. For example, a EWSPercentTimeInCAS throttling value of 90 results in a throttling threshold of 54 seconds (90/100 * 60 seconds).
• EWSPercentTimeInMailboxRPC – Identifies how much time all concurrent EWS connections can consume while accessing a mailbox via RPC requests, per minute. This is calculated on a per-user basis. This budget is calculated by dividing the throttling value for this setting by 100 and then multiplying the results by 60 seconds. For example, a EWSPercentTimeInMailboxRPC throttling value of 60 results in a throttling threshold of 36 seconds (60/100 * 60 seconds). This means that a single connection can consume 36 seconds per minute as long as there are no other connections. Two connections that started at the same time can only consume 18 seconds each per minute. This is based on a threshold setting of 60.

For more information about EWS throttling policy, see EWS Best Practices: Understanding Throttling Policies.

What are the specific Exchange Web Services limits?

The following are the specific EWS throttling limits:

• maxAllowedContentLength (IIS7) – Identifies the maximum accepted content length of HTTP requests. This maximum length is 35,000,000 bytes, which translates to 25 MB of base64-encoded data.
• maxReceivedMessageSize (WCF) – Identifies the maximum message size that is accepted by EWS. This maximum message size is 35,000,000 bytes, which translates to 25 MB of base64-encoded data.

Note   The values for this limit differ for an on-premise Exchange 2010 deployment. In the initial release version of Exchange 2010, the message size limit is 10 MB. In Exchange 2010 Service Pack 1 (SP1), the message size limit is 35 MB.

• maxRequestLength (ASP.Net) – Not used.

The Exchange Interoperability documentation team is pleased to announce the launch of Exchange Server Interoperability Guidance that supplements the information available in the Microsoft Exchange Server protocol documentation and the Microsoft Exchange Server and Outlook Standards documentation. Whether you’re an Exchange interoperability expert, just getting started, or somewhere in between, we’re confident that this supplemental information will be a valuable resource for you.

In the first article, Exploring the Microsoft Exchange Server Open Specifications, Kim Brandl reviews the types of protocols, structures, algorithms, and standards that the Microsoft Exchange Server Open Specifications define, discusses how to get started using the specifications, explores the kinds of content that you’ll find in the various types of specifications, and addresses some key points to help you derive the maximize benefit from the specifications. Check out Exploring the Microsoft Exchange Server Open Specifications now, and stay tuned for additional technical articles coming soon!

Kim Brandl
Exchange Interoperability
Microsoft Corporation

This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers.

Autodiscover is a process by which a Microsoft Exchange Server client can determine the URL of the Microsoft Exchange ActiveSync endpoint by using only a mailbox SMTP address and user credentials. During the Autodiscover process, the client uses the mailbox SMTP address to determine the Autodiscover service endpoint URL and sends a request to the Autodiscover service that includes the mailbox SMTP address. A successful call to the Autodiscover service results in a response that contains the Exchange ActiveSync endpoint URL that the client will use to access the mailbox. This not only simplifies initial client configuration for the end user, but also gives the client a mechanism by which to recover from errors and respond to changes in the Microsoft Exchange environment automatically.

In this blog post, I describe the Autodiscover process from the perspective of an Exchange ActiveSync client developer, including the following:

• The process of finding and calling the Autodiscover service.
• The specific requests and responses that are used during the Autodiscover process.
• When clients should call Autodiscover. 

Finding and calling the Autodiscover service

A client needs only an email address and user credentials to successfully find and call the Autodiscover service. The client should parse the email address to get the domain information, which is everything to the right of the “@” character.

In the following procedure, woodgrovebank.com is the domain from the email address chris@woodgrovebank.com. If the domain information includes a subdomain, such as sales.woodgrovebank.com, the client should use the sales.woodgrovebank.com subdomain first and then, if the procedure fails, try again using the domain woodgrovebank.com. The client uses this domain to construct the Autodiscover service endpoint URLs.

The following procedure describes the Autodiscover process for Exchange ActiveSync clients.

1. The client sends an Autodiscover request to https://woodgrovebank.com/autodiscover/autodiscover.xml and does one of the following:

• If the Autodiscover attempt succeeds, the client proceeds to step 5.
• If the Autodiscover attempt fails, the client proceeds to step 2.

2. The client sends an Autodiscover request to https://autodiscover.woodgrovebank.com/autodiscover/autodiscover.xml, and does one of the following:

• If the Autodiscover attempt succeeds, the client proceeds to step 5.
• If the Autodiscover attempt fails, the client proceeds to step 3.

3. The client sends an unauthenticated GET method request to http://autodiscover.woodgrovebank.com/autodiscover/autodiscover.xml. (Note that this is a non-SSL endpoint).The client does one of the following:

• If the GET request returns a 302 redirect response, it gets the redirection URL from the Location HTTP header, and validates it as described in the section “Redirect responses”. The client then does one of the following:
  • If the redirection URL is valid, the client tries the URL, and does one of the following:
    • If the attempt succeeds, the client proceeds to step 5.
    • If the attempt fails, the client proceeds to step 4.
  • If the redirection URL is not valid, the client proceeds to step 4.
• If the GET request does not return a 302 redirect response, the client proceeds to step 4.

4. The client performs a DNS query for an SRV record for _autodiscover._tcp.woodgrovebank.com. The query might return multiple records. The client selects only records that point to an SSL endpoint and that have the highest priority and weight. One of the following occurs:

• If no such records are returned, the client proceeds to step 6.
• If records are returned, the application randomly chooses a record in the list, and validates the endpoint that it points to by following the process described in the section “Redirect Response”. The client then does one of the following:
  • If the redirection URL is valid, it tries the URL, and one of the following occurs:
    • If the attempt succeeds, the client proceeds to step 5.
    • If the attempt fails, the client proceeds to step 6.
  • If the redirection URL is not valid, the client proceeds to step 6.

5. When a valid Autodiscover request succeeds, the following takes place:

• If the server responds with an HTTP 302 redirect, the client validates the redirection URL according to the process defined in the section “Redirect responses”, and does one of the following:
  • If the redirection URL is valid, the client tries the URL, and does one of the following:
    • If the attempt succeeds, the client resumes step 5 from the beginning.
    • If the attempt fails, the client proceeds to step 6.
  • If the redirection URL is not valid, the client proceeds to step 6.
• If the server responds with a valid Autodiscover response, the client does one of the following:
  • If the value of the Action element is "Redirect", it gets the redirection email address from the Redirect element, and returns to step 1 using this new email address.
  • If the value of the Action element is "Settings", the client has successfully received the requested configuration settings for the specified user. The client does not need to proceed to step 6.

6. If the client cannot contact the Autodiscover service, the client should ask the user for the Exchange server name and use it to construct an Exchange ActiveSync URL, similar to the following: http://servername/Microsoft-Server-ActiveSync. The client should try to use this URL for future requests.

Autodiscover requests and responses

The preceding procedure mentions Autodiscover requests and responses. Microsoft Exchange publishes a "plain old XML" (POX) endpoint for the Autodiscover service. (For more information, see Autodiscover Reference (POX) on MSDN.) These responses can be quite large. Because Exchange ActiveSync is a mobile protocol, a more concise Autodiscover schema called "mobilesync" is defined specifically for Exchange ActiveSync clients.

The following is an example of an Exchange ActiveSync Autodiscover request.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/requestschema/2006">

     <Request>

            <EMailAddress>chris@woodgrovebank.com</EMailAddress>

            <AcceptableResponseSchema>

             http://schemas.microsoft.com/exchange/autodiscover/mobilesync/

             responseschema/2006

            </AcceptableResponseSchema>

     </Request>

</Autodiscover>

Successful response

A successful Exchange ActiveSync response contains URL settings for Exchange ActiveSync. Settings in the Exchange ActiveSync Autodiscover response can contain two server sections: one with the type “MobileSync”, which is the Exchange ActiveSync endpoint URL, and one with the type “CertEnroll”, which is used to obtain a client certificate for SSL negotiation. (For more information about this response, see [MS-ASCMD] ActiveSync Command Reference Protocol Specification section 4.2.4.)

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover

xmlns:autodiscover="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

            <autodiscover:DisplayName>Chris Gray</autodiscover:DisplayName>

            <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

        </autodiscover:User>

        <autodiscover:Action>

            <autodiscover:Settings>

                <autodiscover:Server>

                    <autodiscover:Type>MobileSync</autodiscover:Type>

                    <autodiscover:Url>

                        https://loandept.woodgrovebank.com/Microsoft-Server-ActiveSync

                    </autodiscover:Url>

                    <autodiscover:Name>

                 https://loandept.woodgrovebank.com/Microsoft-Server-ActiveSync

             </autodiscover:Name>

                </autodiscover:Server>

                <autodiscover:Server>

                    <autodiscover:Type>CertEnroll</autodiscover:Type>

                    <autodiscover:Url>https://cert.woodgrovebank.com/CertEnroll</autodiscover:Url>

                    <autodiscover:Name />

                   <autodiscover:ServerData>CertEnrollTemplate</autodiscover:ServerData>

                </autodiscover:Server>

            </autodiscover:Settings>

        </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

Redirect responses

Redirection to a different URL can be in the form of an HTTP 302 response. In the following example, an Autodiscover request is being redirected to a different URL. The client should try to send an Autodiscover request to the URL in the response. If the request sent to the redirect location fails, the client should stop and inform the user that Autodiscover has failed.

HTTP/1.1 302 Found

Location: https://autodiscover.us.woodgrovebank .com/autodiscover/autodiscover.xml

Redirects can also come from within the details of an Autodiscover response, as shown in the following example. In this case, the client is being directed to start the Autodiscover process over with a new email address.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns:autodiscover="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

           <autodiscover:DisplayName>Chris Gray</autodiscover:DisplayName>

           <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

        </autodiscover:User>

        <autodiscover:Action>

           <autodiscover:Redirect>chris@loandept.woodgrovebank.com </autodiscover:Redirect>

        </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

The client should start from step 1 in the procedure with the email address from the redirect response, chris@loandept.woodgrovebank.com.

Error responses

Errors can come in the form of HTTP 403 or 404 error responses, or in the Error section of an Autodiscover response. The client should consider these errors permanent and move on to the next step in the Autodiscover URL location process. An HTTP 401 response indicates that authentication failed. The client can choose to present the user an opportunity to enter credentials again.

Error responses from Autodiscover can indicate a problem with the request the client sent or a problem on the server side. In the following example, there was a problem contacting the directory service on the server side. Because this error is on the server side, the client should continue on to the next step in the Autodiscover URL location process. The client can also choose to retry this request, as the error might be transient.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover xmlns:autodiscover="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

    <autodiscover:Response>

        <autodiscover:Culture>en:us</autodiscover:Culture>

        <autodiscover:User>

           <autodiscover:EMailAddress>chris@woodgrovebank.com</autodiscover:EMailAddress>

       </autodiscover:User>

       <autodiscover:Action>

           <autodiscover:Error>

               <Status>1</Status>

               <Message>The directory service could not be reached</Message>

               <DebugData>MailUser</DebugData>

           </autodiscover:Error>

       </autodiscover:Action>

    </autodiscover:Response>

</Autodiscover>

Error responses can also indicate problems with the Autodiscover request sent by the client. The following example shows an error code 600 response, which indicates an invalid request. A 601 response would indicate that the requested schema version is not supported by the server.

<?xml version="1.0" encoding="utf-8"?>

<Autodiscover

xmlns:autodiscover="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006">

   <autodiscover:Response>

      <autodiscover:Error Time="16:56:32.6164027" Id="1054084152">

          <autodiscover:ErrorCode>600</autodiscover:ErrorCode>

          <autodiscover:Message>Invalid Request</autodiscover:Message>

          <autodiscover:DebugData />

      </autodiscover:Error>

   </autodiscover:Response>

</Autodiscover>

When should the client perform Autodiscover?

Because Autodiscover requires only an email address and password, using Autodiscover can make the initial configuration of an email account easy for a user. After performing Autodiscover in an initial account configuration, the device should cache the Exchange ActiveSync URL that is returned in the successful response.

Autodiscover is equally important after the initial configuration of the email client as a method for recovering from transient errors. If the client receives HTTP 401, 403, 404, or 500 responses, timeouts, or any response that indicates a DNS lookup failure, it should run Autodiscover to see if it gets a new URL. For more information, see [MS-ASHTTP] ActiveSync HTTP Protocol Specification section 3.1.5.2.1.

The client can also receive an HTTP 451 redirect response, as specified in [MS-ASHTTP] ActiveSync HTTP Protocol Specification section 3.1.4.2.2. This response indicates that the client sent a request to a URL that is no longer the optimum endpoint URL for the mailbox the client is trying to access. This can occur when a mailbox moves from one Active Directory site to another. For more information, see Understanding Proxying and Redirection on Microsoft TechNet. The client will continue to receive the 451 error until it sends requests to the new endpoint.

Typically, the 451 response contains an X-MS-Location header that indicates the new Exchange ActiveSync URL for the client to use. When this header is present, the client does not need to use Autodiscover to get the new URL; it can use the URL from the header. However, the X-MS-Location header is optional. If the header is not present, the client should perform Autodiscover to get a new Exchange ActiveSync URL. The following example shows a 451 error response.

HTTP/1.1 451

Date: Tue, 08 Dec 2009 19:43:24 GMT

Server: Microsoft-IIS/7.0

X-Powered-By: ASP.NET

X-AspNet-Version: 2.0.50727

X-MS-Location: https://mail.woodgrovebank .com/Microsoft-Server-ActiveSync

Cache-Control: private

Content-Length: 0

A 302 redirect response is expected and should be followed only during the Autodiscover process. If the client receives a 302 redirect in response to a command, such as FolderSync, it should not follow the redirect. Instead, the client should go through the Autodiscover process again to get a new URL.

Related Resources

[MS-ASCMD]: ActiveSync Command Reference Protocol Specification

[MS-ASHTTP]: ActiveSync HTTP Protocol Specification

Understanding Proxying and Redirection

Understanding the Autodiscover Service

Understanding Exchange ActiveSync Autodiscover

Autodiscover and Exchange 2007

Post written by: Matt Stehle, Microsoft Corporation

Network load balancing for Microsoft Exchange Online as part of Microsoft Office 365 ensures that tenant client access loads are properly balanced. Network load balancing also has implications for Client Access server affinity. Some stateful client features require Client Access server affinity. This is because some state information is cached on Client Access servers. Both Exchange Web Services (EWS) and MAPI clients include ways to maintain Client Access server affinity through the network load balancers.

Client Access server affinity and Exchange Web Services

Client Access server affinity is important for EWS. Using the Client Access server that services a mailbox improves both performance and function. Using a Client Access server that does not service the particular mailbox to handle a request can negatively affect performance, and in some cases, the request might fail. Requests for features such as event notification subscriptions require stateful information, and state information is maintained on the Client Access server that services the mailbox. Client Access server affinity is required to maintain state information about which notifications have been delivered to the client. For example, if the notification request is not sent to the correct Client Access server, the server will respond with the ErrorSubscriptionNotFound error.

The key to maintaining Client Access server affinity for EWS is the exchangecookie cookie. The exchangecookie cookie associates a client with a specific Client Access server — specifically, the Client Access server that services the target mailbox. The network load balancer uses the exchangecookie cookie to maintain Client Access server affinity for a client. The first response that the client receives from the server will contain the exchangecookie cookie. For all subsequent EWS client requests for that mailbox, the exchangecookie cookie must persist, in order to maintain Client Access server affinity. The client should preserve the cookie after each response, because in some cases the cookie might change mid-session. The exchangecookie cookie should persist for use in all future requests.

Clients that use the EWS Managed API 1.1 and the EWS Java API 1.1 do not have to manage the exchangecookie cookie as this is done automatically. If you create a custom client, make sure that the exchangecookie cookie persists for each mailbox you are accessing.

Client Access server affinity and MAPI

MAPI Client Access server affinity is maintained through the network load balancer by the OutlookSession session. You can maintain Client Access server affinity for a client by using a single OutlookSession session for the client. The client cannot rely on state information maintained on the Client Access server if subsequent sessions are opened since different sessions are not necessarily handled by the same Client Access server that handled a previous session.

This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers. 

In this post, we are using Exchange ActiveSync protocol version 14.1. Where applicable, we note differences between protocol versions.

Meeting requests are important for information workers who use Microsoft Exchange. Meeting requests inform attendees of a meeting, automatically book meeting time on the organizer's and attendees' calendars, provide reminders for meetings, and enable the booking of conference rooms. This post provides information for developers about working with meeting requests, including the following topics:

• How meeting requests are created by using Exchange ActiveSync.
• How invitees' Exchange ActiveSync clients interpret meeting requests.

The following figure shows an overview of the meeting request process and the two key scenarios involved. In this example, Exchange ActiveSync user Alice requests a meeting with Bob from her Exchange ActiveSync client. Bob sees the meeting request on his Exchange ActiveSync device.

Figure 1:   Meeting request process

Scenario 1: Organizer creates meeting request by using an Exchange ActiveSync client

A meeting starts out as a meeting request. The meeting organizer requests that attendees agree to participate in the meeting at a specified date, time, and location. Meeting requests are composed of the following two elements:

1.      A calendar item that reflects the proposed meeting on the organizer's and invitees' calendars.

2.      An invitation email sent by the organizer to invitees to notify them of the proposed meeting and solicit their responses.

In order for a user to create meeting requests, an Exchange ActiveSync client must do the following:

• Add a new calendar event to the organizer's calendar that includes the meeting details.

• Send an email to prospective attendees that includes the meeting details and response options.

After the Exchange ActiveSync client sends an email message that includes the meeting invitation, the Exchange server sends the invitation and saves a copy in the Sent Items folder. The following figure shows the client requests and server responses when a user, Alice, creates a meeting request from her Exchange ActiveSync client. The syncing of the Sent Items folder is optional.

Figure 2:   Meeting request process

Adding meeting details to the organizer's calendar

Request to create the calendar item

When a user organizes a new meeting on the Exchange ActiveSync client, the client must create a meeting item on the organizer's calendar. The client adds the new calendar item to the Calendar collection. The calendar item contains all the meeting details, including meeting attendees. The following example shows an Exchange ActiveSync Sync command XML request that adds a meeting to Alice's calendar when she organizes a meeting and invites Bob.

For a list of and information about the Calendar schema elements for Exchange ActiveSync, see [MS-ASCAL]:  ActiveSync Calendar Class Protocol Specification section 2.2.2.

In the meeting request, the Exchange ActiveSync client must specify the start time and end time of the proposed event; this information is included in the StartTime and EndTime elements. Both dates have to be valid values of the dateTime type, as described in [MS-ASDTYPE]: ActiveSync Data Types section 2.3. All dates must be specified in Coordinated Universal Time (UTC), without any punctuation separators. Optionally, the client can use the DtStamp element to specify when the calendar item was created.

The client should specify the time zone in the request. If the time zone is not specified, the Exchange server uses its current  time zone for the meeting. For more information about the format of the time zone, see [MS-ASDTYPE] section 2.6.4.

Optionally, the client can mark the organizer's calendar by specifying the BusyStatus element. The following are the possible values for the BusyStatus element:

·        0 – Free

·        1 – Tentative

·        2 – Busy

·        3 – Out of office

If the organizer did not explicitly specify his or her attendance status, the client should use a value of 2 for the BusyStatus element to mark the meeting status as busy. If the client does not provide this value, the server uses a busy status by default.

The client should provide a MeetingStatus element for meetings. When the client saves a meeting to the organizer's calendar, it should set the value of this element to 1, which indicates that the item is a meeting.

A meeting must include the Attendees element, which contains a collection of Attendee elements. Each Attendee element must include at least one Email and one Name element; these contain the name and email address of the attendee. Optionally, the Attendee element can include values for the AttendeeStatus and AttendeeType elements. When the meeting is created, the AttendeeStatus element contains a value of 0. This value changes when attendees respond to the meeting request. If present, the AttendeeType element must be set to one of the following values:

·        1 – Required

·        2 – Optional

·        3 – Resource

Server response to the request to create the calendar item

The Exchange server sends a response to the Exchange ActiveSync client's request. The response indicates the status of the Calendar Sync command operation as well as the status of the individual meeting request. If the item was added correctly (as indicated by a Status element value of 1 in the response for both the item and the collection), the server issues a ServerId element value for the item in lieu of the temporary ClientId element value that the client assigned to it, as shown in the following example.

The client has to associate the newly issued ServerId value with this calendar item. For more information about status response values, see [MS-ASCMD]: ActiveSync Command Reference Protocol Specification.

Informing attendees of the meeting details by email notification

The email notification must make it clear to the recipients that its purpose is to inform them of the meeting request. It can also optionally solicit invitee responses to the request, and automatically block the meeting time on prospective attendees' calendars.

Client request to send the meeting email message

Exchange ActiveSync clients use the SendMail command to send MIME-formatted email messages to the server, including calendaring information structured according to a known calendaring format.

The iCalendar format is the most common calendaring format; this format is supported by a variety of clients. The following example shows the Exchange ActiveSync SendMail request that Alice's Exchange ActiveSync client sends.

The email message contains multiple parts. The message may contain a plain text part, which includes the body text of the meeting request. Several different calendar request formats are available for meeting request messages. Microsoft Exchange supports the iCalendar and TNEF formats. Each of these formats are included in a separate MIME part in the meeting request message. (For more information about MIME, see RFC 2045, RFC 2046, and RFC 2047.) Most clients use the iCalendar format for the meeting request, encoded in base64. Meeting requests have a content type of text/calendar with the method parameter set to “REQUEST”. The following section provides more detail about the iCalendar format.

iCalendar format

The iCalendar format is a file format (extension .ics, .ical) that represents calendaring information such as meeting requests, meeting responses, and free/busy information. For more information about this format, see RFC 2445, RFC 5546, and [MS-OXCICAL]: iCalendar to Appointment Object Conversion Protocol Specification.

This standard enables users of different calendaring systems (including clients and servers) to exchange calendaring information. iCalendar information is transported across the Internet in MIME format. The MIME body that contains the iCalendar information has a content type of text/calendar. The following example shows a typical iCalendar meeting request.

Server response to the client request to send the meeting email message

The response to SendMail command has no XML body (Content-Length = 0) if the SendMail command finishes successfully, as shown in the following example.

The server first responds to the SendMail request from the organizer's Exchange ActiveSync client, and then tries to send the message to the attendees. For this reason, a positive response to the SendMail request does not guarantee that the message was sent out successfully. The Exchange ActiveSync client can still receive a non-delivery report notification if the mail recipients are not found. For more information about the SendMail status values, see [MS-ASCMD] section 2.2.3.152.13. Non-delivery report responses should be handled in the same way that email responses are handled.

Before the Exchange server sends the email message, it interprets the iCalendar information and structures the message to the attendees to reflect that it is a meeting request.

Saving the meeting notification in Sent Items

After the Exchange ActiveSync client submits the meeting request email to the server, the Exchange server sends the email message to all the invited attendees. In addition, the Exchange server parses the iCalendar information that is embedded in the email. This way, it adds the email message to the Sent Items folder as the appropriate type; that is, a meeting request. The next time the Exchange ActiveSync client syncs the Sent Items folder, the meeting request email message will be added to the Sent Items folder on the client.

Client request to sync the Sent Items folder

The client syncs the Sent Items folder as shown in the following example.

Server response to the request to sync the Sent Items folder

The server adds a new item with the MessageClass element set to IPM.Schedule.Meeting.Request, as shown in the following example. This item contains all the meeting details.

The meeting request email that is sent to the attendees is of type IPM.Schedule.MeetingRequest and contains a MeetingRequest container. (For more information about the MeetingRequest container, see [MS-ASEMAIL]: ActiveSync E-Mail Class Protocol Specification section 2.2.2.14). This container describes the properties of the meeting. In addition, it now contains the GlobalObjId element value that was assigned to the meeting item by the server.

The GlobalObjId element value identifies the meeting request and allows the client to determine whether it corresponds to an existing object in the Calendar. For more information about the GlobalObjId element, see [MS-ASEMAIL] section 2.2.2.14.15. The UID element value assigned to the calendar item by the Exchange ActiveSync client is included in the GlobalObjId element value that the server returns. The GlobalObjId element value does not change when the meeting is updated. This enables the client to identify which meeting a particular notification corresponds to.

This meeting request message that is added to the organizer's Sent Items folder should not expose any response options to the user because it is in the organizer's mailbox.

Scenario 2: A meeting invitee receives a meeting request on the Exchange ActiveSync client

When an organizer sends a meeting request, the invitees' Exchange ActiveSync client must be able to receive the request, interpret it, and present it to the invitee as a meeting invitation. The meeting request should appear in the invitee's Inbox, and a placeholder Calendar item for the meeting should appear on the invitee's Calendar. The invitee should be able to accept, tentatively accept, or decline the meeting request, either from the meeting invitation or from the Calendar placeholder item, and send his or her response the meeting organizer.

The following figure shows the operations involved in sending a meeting request to an Exchange ActiveSync client. In this example, Bob is the meeting invitee.

Figure 2:   Sending a meeting request to an Exchange ActiveSync client

Adding the meeting request to the invitee's Inbox

When the meeting invitation first arrives in the invitee's mailbox, it is in the form of a meeting request in the Inbox.

Receiving the meeting request

The Exchange ActiveSync client receives the meeting request upon issuing a Sync command request for the invitee's Inbox. We recommend that Exchange ActiveSync clients request body items in HTML format by setting the BodyPreference element to 2. HTML provides rich content formatting that the client can then render. The meeting request is shown in the following example.

Server response to the Sync command request

The organizer's Exchange server converts the item's iCalendar information and parses it into a message class of IPM.Schedule.Meeting.Request, which is then synced to the invitee's Inbox, as shown in the following example.