Exchange Web Services Managed API 1.2.1 – now released!

  • Article

The latest release of the EWS Managed API, version 1.2.1, is now available. The EWS Managed API 1.2.1 includes new Exchange Web Services (EWS) client logging features for Exchange Online as part of Office 365, as well as some minor bug fixes. You can download the EWS Managed API 1.2.1 from the Microsoft Download Center.

What’s new in the EWS Managed API 1.2.1

The EWS Managed API 1.2.1 includes new Exchange Online–specific functionality for logging client access and client latencies. This new functionality is implemented by means of two new HTTP headers: RequestId and X-ClientStatistics. Starting with the EWS Managed API 1.2.1, this functionality is enabled by default.  You can enable this functionality in previous versions of the EWS Managed API by accessing the HttpHeaders and HttpResponseHeaders collection on the ExchangeService object.

This change allows for the debugging of communication issues that occur between Exchange Online and the EWS Managed API. In fact, this functionality should be implemented by any EWS client that will be targeting Exchange Online.

The new RequestId header is returned in every response from EWS in versions of Exchange starting with Exchange Server 2010 SP2 RU2, and in Exchange Online. While this header is available for both an on-premise Exchange deployment and Exchange Online, it is particularly relevant for Exchange Online. The RequestId header contains a GUID value that uniquely identifies your request in the Office 365 server-side logs across all the Office 365 data centers. Essentially, you should log these requests with the client. If a support incident does occur, you can provide the RequestId to the Office 365 support engineers to help them identify issues related to the request.

You can use the new X-ClientStatistics header to provide additional logging information for Exchange Online. You can enable additional performance logging for Exchange Online by providing the following information in your requests:

  • The RequestId received from a previous request
  • The client-logged round trip time between the request and response
  • The SOAP action

Note that the X-ClientStatistics header can be used to report data back to Office 365 at any time and that it can batch multiple latencies in a single header. This is another useful resource for Office 365 support engineers.

Important: The X-ClientStatistics functionality is not available for on-premise Exchange deployments.

The RequestId and X-ClientStatistics headers are both implemented in the EWS Managed API 1.2.1. The RequestId header is sent by Exchange with every response. You can disable the X-ClientStatistics functionality on the ExchangeService object by setting the new SendClientLatencies properties to false.

If you are using Exchange Online but you are not using the EWS Managed API, we recommend that you capture and log the RequestId header and the send X-ClientStatistics header. The following are the header definitions: 

  • RequestId: <GUID>; where <GUID> is the unique request identifier.
  • X-ClientStatistics: MessageId=<RequestIdFromPreviousResponse>,ResponseTime=<EndToEndLatencyInMiliseconds>,SoapAction<operation>; where <RequestIdFromPreviousResponse> is a request identifier from a previous response, <EndToEndLatencyInMiliseconds> is the client-logged round trip time between when the request was submitted and when the response was received for the request-response identified by the RequestId, and <operation> identifies the SOAPAction header for the request identified by the RequestId header. If you are sending multiple client latency reports back to the server, you must separate the latencies with a semicolon.

The EWS Managed API 1.2.1 fixes two Autodiscover redirect issues for scenarios in which an Exchange Server 15 user targets a request to an Exchange 2010 server.

While not a large set of changes, they are still interesting. These updates will primarily help Office 365 support engineers help you if your application experiences issues communicating with the server. This should help make our service perform better, and your problems to be solved in a shorter amount of time.