Compartir a través de

  • Artículo

Versioning EWS Requests in Exchange 2010

Last modified: October 14, 2009

Applies to: Exchange Server 2007 | Exchange Server 2010

Request versioning provides a way to indicate to the Exchange server the type of response that an Exchange Web Services (EWS) client expects. For example, an Exchange 2007 SP1–generated proxy throws an exception if it deserializes a request that includes new Exchange 2010 elements. Exchange Web Services uses the versioning SOAP header to generate responses that are valid for the specified version. Exchange 2010 includes a SOAP header that identifies the schema against which the request is validated and restricts the response based on that schema. In addition to new objects and operations in Exchange 2010, there are some API behavior changes between the Exchange Web Services schema versions. These changes include the Exchange Web Services identifier format and how time zones are implemented.

Requests that do not include version headers are handled as requests from the initial release version of Exchange 2007. If the Exchange 2010 version is not specified, schema validation errors might occur because the request will be validated against the initial release version of the Exchange Web Services schema instead of the Exchange 2010 version of the schema. The latest EWS schema includes new features and bug fixes that cannot be included in older schemas due to compatibility problems. By specifying the most recent request version in the SOAP header of requests, you can ensure that your application gets the latest bug fixes and most up-to-date EWS behavior.

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

  1. Create an instance of an ExchangeServiceBinding object.

    ExchangeServiceBinding esb = new ExchangeServiceBinding();

  2. Create an instance of a new RequestServerVersion object.

    esb.RequestServerVersionValue = new RequestServerVersion();

  3. Set the Version property on the RequestServerVersion object to one of the following ExchangeVersionType enumeration values:

    • Exchange2010

    • Exchange2007_SP1

    • Exchange2007

    esb.RequestServerVersionValue.Version = ExchangeVersionType.Exchange2010;

To add versioning information to the XML SOAP header

  1. Create the SOAP header.

  2. Create the RequestServerVersion XML element as the first inner XML element in the SOAP header.

  3. Create a Version attribute in the RequestServerVersion element.

  4. Set the Version attribute to either Exchange2007, Exchange2007_SP1, or Exchange2010.

Example

The following code example shows you how to version an Exchange 2010 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 App 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.Exchange2010;
    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 App 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 2010 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="Exchange2010"/>
  </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 2010 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="Exchange2010" 
                         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>

See Also

Other Resources

EWS Client Development in Exchange 2010