Home Library Learn Downloads Support Community
Sign in | United States - English | |
1 out of 2 rated this helpful - Rate this topic

Versioning EWS requests

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 Microsoft Exchange Web Services (EWS) Managed API objects, methods, and properties that are available in the specified version. You can specify Microsoft Exchange Server 2010 Service Pack 1 (SP1), Microsoft Exchange Server 2010, or Microsoft Exchange Server 2007 Service Pack 1 (SP1). If you do not specify a version, EWS will use the latest version of Microsoft Exchange Server that is known to the EWS Managed API.

In each EWS response, the version of Microsoft 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.

XML
Copy 

<ServerVersionInfo MajorVersion="14" MinorVersion="0" MajorBuildNumber="478" MinorBuildNumber="0" Version="Exchange2010_SP1" 
               xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types" 
               xmlns="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema" />

  • Instantiate the ExchangeService object without specifying a version.

    C#
    Copy 
    ExchangeService service = new ExchangeService();

  • Instantiate the ExchangeService object and specify the version as ExchangeVersion.Exchange2007_SP1.

    C#
    Copy 
    ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2010_SP1);

  • Instantiate the ExchangeService object and specify the version as ExchangeVersion.Exchange2010.

    C#
    Copy 
    ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2010);

  • Instantiate the ExchangeService object and specify the version as ExchangeVersion.Exchange2007_SP1.

    C#
    Copy 
    ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);

This section includes examples of successful and unsuccessful request versioning.

The following example shows how to version an Exchange 2010 request 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.)

C#
Copy 
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
Copy 
<?xml version="1.0" encoding="utf-8" ?> 
   <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"          
                  xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
                  xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://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
Copy 
<?xml version="1.0" encoding="utf-8" ?> 
   <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> 
      <s:Header> 
         <h:ServerVersionInfo MajorVersion="14" MinorVersion="0" MajorBuildNumber="478" MinorBuildNumber="0" Version="Exchange2010" 
               xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types" 
               xmlns="http://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="http://schemas.microsoft.com/exchange/services/2006/messages"    
                               xmlns:t="http://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>

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.

C#
Copy 
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();
   }
}
  • 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.
  • 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.
  • 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.
Did you find this helpful?
(1500 characters remaining)