Versioning EWS requests by using the EWS Managed API 2.0
Last modified: April 09, 2013
Applies to: EWS Managed API | Exchange Server 2007 Service Pack 1 (SP1) | Exchange Server 2010
Note: This content applies to the EWS Managed API 2.0 and earlier versions. For the latest information about the EWS Managed API, see Web services in Exchange.
Versioning provides a way for an Exchange Web Services (EWS) client to indicate the contract that the server should use to validate and process the client request. This enables the client to access the EWS Managed API objects, methods, and properties that are available in the specified version. You can specify Exchange Server 2013, Exchange Server 2010 Service Pack 2 (SP2), Exchange 2010 Service Pack 1 (SP1), Exchange 2010, or Exchange 2007 SP1. If you do not specify a version, EWS will use the latest version of Exchange Server that is known to the EWS Managed API.
In each EWS response, the version of Exchange that generated the response is indicated by the ServerVersionInfo element. The following example shows a ServerVersionInfo element that represents a response from Exchange 2010 SP1.
<ServerVersionInfo MajorVersion="14" MinorVersion="0" MajorBuildNumber="478" MinorBuildNumber="0" Version="Exchange2010_SP1"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/types" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
To specify the latest version of Exchange Server known to the EWS Managed API
Instantiate the ExchangeService object without specifying a version.
ExchangeService service = new ExchangeService();
To specify Exchange 2013
Instantiate the ExchangeService object and specify the version as ExchangeVersion.Exchange2013.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2013);
To specify Exchange 2010 SP2 or Exchange 2010 SP3
Instantiate the ExchangeService object and specify the version as ExchangeVersion.Exchange2010_SP2.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2010_SP2);
To specify Exchange 2010 SP1
Instantiate the ExchangeService object and specify the version as ExchangeVersion.Exchange2010_SP1.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2010_SP1);
To specify Exchange 2010
Instantiate the ExchangeService object and specify the version as ExchangeVersion.Exchange2010.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2010);
To specify Exchange 2007 SP1, Exchange 2007 SP2, or Exchange 2007 SP3
Instantiate the ExchangeService object and specify the version as ExchangeVersion.Exchange2007_SP1.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
Example
This section includes examples of successful and unsuccessful request versioning.
Successful Versioning
The following example shows how to version an EWS request to use the Exchange 2010 EWS request and response by using the ExchangeService object and how to create a folder associated message by using the EWS Managed API. The example will run without error because the IsAssociated property on the EmailMessage object is available in Exchange 2010. (Note that folder associated items are not visible in the mailbox; setting the IsAssociated property on an item will create that item as a hidden item.)
static void UsingVersioning()
{
// Connect to Exchange Web Services as user1 at contoso.com, targeting Exchange 2010.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2010);
service.Credentials = new WebCredentials("user1", "password", "contoso.com");
service.AutodiscoverUrl("user1@contoso.com");
try
{
// Create and save a folder associated message in the Inbox.
EmailMessage message = new EmailMessage(service);
message.IsAssociated = true;
message.Subject = "Interesting subject";
message.Save(WellKnownFolderName.Inbox);
// Write confirmation message to the console window.
Console.WriteLine("Folder associated message created & saved.");
Console.ReadLine();
}
catch (Exception ex)
{
// Write error message to the console window.
Console.WriteLine("Error: " + ex.Message);
Console.ReadLine();
}
}
The following example shows the XML that is sent by using the Save method.
<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010" />
</soap:Header>
<soap:Body>
<m:CreateItem MessageDisposition="SaveOnly">
<m:SavedItemFolderId>
<t:DistinguishedFolderId Id="Inbox" />
</m:SavedItemFolderId>
<m:Items>
<t:Message>
<t:Subject>Interesting</t:Subject>
<t:IsAssociated>true</t:IsAssociated>
</t:Message>
</m:Items>
</m:CreateItem>
</soap:Body>
</soap:Envelope>
The following example shows the XML that is returned by using the Save method. The ItemId and ChangeKey attributes have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8" ?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="14" MinorVersion="0" MajorBuildNumber="478" MinorBuildNumber="0" Version="Exchange2010"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/types" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:CreateItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:CreateItemResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Items>
<t:Message>
<t:ItemId Id="AQMkAGY" ChangeKey="CQAAA " />
</t:Message>
</m:Items>
</m:CreateItemResponseMessage>
</m:ResponseMessages>
</m:CreateItemResponse>
</s:Body>
</s:Envelope>
Unsuccessful Versioning
The following example shows an attempt to version an Exchange 2007 SP1 request by using the ExchangeService object and to create a folder associated message by using the EWS Managed API. The EWS Managed API will throw an exception if the example is run because the IsAssociated property on the EmailMessage object is not available in Exchange 2007 SP1.
static void UsingVersioning()
{
// Connect to Exchange Web Services as user1 at contoso.com, targeting Exchange 2007 SP1.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
service.Credentials = new WebCredentials("user1", "password", "contoso.com");
service.AutodiscoverUrl("user1@contoso.com");
try
{
// Create and save a folder associated message in the Inbox.
EmailMessage message = new EmailMessage(service);
message. IsAssociated = true;
message.Subject = "Interesting subject";
message.Save(WellKnownFolderName.Inbox);
// Write confirmation message to the console window.
Console.WriteLine("Folder associated message created & saved.");
Console.ReadLine();
}
catch (Exception ex)
{
// Write error message to the console window.
Console.WriteLine("Error: " + ex.Message);
Console.ReadLine();
}
}
Robust programming
Write appropriate error handling code for common search errors.
Review the client request XML that is sent to the Exchange server.
Review the server response XML that is sent from the Exchange server.
Security
Use HTTP with SSL for all communication between client and server.
Always validate the server certificate that is used to establish the SSL connections. For more information, see Validating X509 certificates by using the EWS Managed API 2.0.
Do not include user names and passwords in trace files.
Ensure that Autodiscover lookups that use HTTP GET to find an endpoint always prompt for user confirmation; otherwise, they should be blocked.