Article
08/21/2009

Versioning Requests (Exchange Web Services)

Topic Last Modified: 2009-07-24

Exchange Web Services (EWS) request versioning was introduced in Microsoft Exchange Server 2007 Service Pack 1 (SP1). Request versioning provides a way for an EWS client to indicate to the Exchange server the type of response that the client expects. For example, an Exchange 2007–generated proxy throws an exception if it deserializes a request that includes new Exchange 2007 SP1 elements. Exchange Web Services uses the versioning SOAP header to generate responses that are valid for the specified version. Exchange 2007 SP1 and Exchange 2007 SP2 include a SOAP header that identifies the schema against which the request is validated and restricts the response based on that schema.

Requests that do not include version headers are handled as requests from the initial release version of Exchange 2007. If an EWS client that has been updated for Exchange 2007 SP2 does not specify a version in the SOAP header, schema validation errors might occur because the request will be validated against the initial release version of the EWS schema instead of the schema that is distributed with Exchange 2007 SP2. The latest EWS schema includes new features and bug fixes that cannot be included in earlier schemas due to compatibility problems. Specifying the most recent request version in the SOAP header of requests ensures that your application gets the latest bug fixes and most up-to-date EWS behavior.

Important

EWS client applications that are updated for Exchange 2007 SP2 should specify Exchange2007_SP1 as the request version in the SOAP header.

The following procedures describe how to add versioning information to the ExchangeServiceBinding object and how to add versioning information directly to the SOAP header.

To add versioning information to the ExchangeServiceBinding object

Create an instance of an ExchangeServiceBinding object.

ExchangeServiceBinding esb = new ExchangeServiceBinding();

Create an instance of a new RequestServerVersion object.

esb.RequestServerVersionValue = new RequestServerVersion();

Set the Version property on the RequestServerVersion object to one of the following ExchangeVersionType enumeration values:
- Exchange2007_SP1
- Exchange2007
```
esb.RequestServerVersionValue.Version = ExchangeVersionType.Exchange2007_SP1;
```
The Version property is set to Exchange2007_SP1 by default.

To add versioning information to the XML SOAP header

Create the SOAP header.
Create the RequestServerVersion XML element as the first inner XML element in the SOAP header.
Create a Version attribute in the RequestServerVersion element.
Set the Version attribute to either Exchange2007 or Exchange2007_SP1.

Example

The following code example shows you how to version an Exchange 2007 SP2 Exchange Web Services request by using the ExchangeServiceBinding object that is created by using WSDL.exe version 2.0.50727.42. The example will not work if the proxy classes are generated against the Exchange Web Services schemas that are included in the initial release version of Exchange 2007. The code example performs an identifier conversion between the Exchange Web Services identifier format and the Outlook Web Access identifier format.

static void UsingVersioning()
{
    // Set the version, credentials, and the Client Access server on ExchangeServiceBinding.
    ExchangeServiceBinding esb = new ExchangeServiceBinding();esb.RequestServerVersionValue = new RequestServerVersion();esb.RequestServerVersionValue.Version = ExchangeVersionType.Exchange2007_SP1;
    esb.Credentials = new NetworkCredential("username", "password", "domain");
    esb.Url = "https://FQDN/ews/exchange.asmx";

    // Create a request to convert identifiers.
    ConvertIdType request = new ConvertIdType();
    request.SourceIds = new AlternateIdType[1];
    request.SourceIds[0] = new AlternateIdType();

    // Convert from the initial release version of Exchange 2007 identifier format to an Outlook Web Access identifier.
    request.SourceIds[0].Format = IdFormatType.EwsLegacyId;
    (request.SourceIds[0] as AlternateIdType).Id = "AAAlAFVz";
    (request.SourceIds[0] as AlternateIdType).Mailbox = "user@example.com";
    request.DestinationFormat = IdFormatType.OwaId;

    try
    {
        // Send the request and get the response.
        ConvertIdResponseType response = esb.ConvertId(request);

        ResponseMessageType[] rmta = response.ResponseMessages.Items;

        foreach (ResponseMessageType rmt in rmta)
        {
            ConvertIdResponseMessageType cirmt = (rmt as ConvertIdResponseMessageType);
            AlternateIdType myId = (cirmt.AlternateId as AlternateIdType);

            string format = myId.Format.ToString();
            string identifier = myId.Id;
            string mailbox = myId.Mailbox;

            Console.WriteLine("Converted to format: {0}\r\nIdentifier: {1}\r\nMailbox: {2}",
                format, identifier, mailbox);
        }
    }

    catch (Exception e)
    {
        Console.WriteLine(e.Message);
    }
}

The following example shows the XML that is sent for an Exchange 2007 SP2 Exchange Web Services request. The version information is located in the SOAP header.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1"/>
  </soap:Header>
  <soap:Body>
    <ConvertId xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
               DestinationFormat="OwaId">
      <SourceIds>
        <t:AlternateId Format="EwsLegacyId" Id="AAAlAFVz" 
                       Mailbox="user@example.com"/>
      </SourceIds>
    </ConvertId>
  </soap:Body>
</soap:Envelope>

The following example shows the XML response to an Exchange 2007 SP2 Exchange Web Services request. The version information is located in the SOAP header.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="1" 
                         MajorBuildNumber="191" MinorBuildNumber="0" 
                         Version="Exchange2007_SP1" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <m:ConvertIdResponse xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                         xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:ConvertIdResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:AlternateId xsi:type="t:AlternateIdType" Format="OwaId" Id="RgAAAAAS2%2" 
                         Mailbox="user@example.com" />
        </m:ConvertIdResponseMessage>
      </m:ResponseMessages>
    </m:ConvertIdResponse>
  </soap:Body>
</soap:Envelope>

Share via

Versioning Requests (Exchange Web Services)

To add versioning information to the ExchangeServiceBinding object

To add versioning information to the XML SOAP header

Example

See Also

Other Resources

Additional resources