Working with Time Zones in Exchange 2010 Exchange Web Services

A more flexible time zone definition structure in Exchange 2010 Exchange Web Services means that EWS can now support changes to daylight saving time rules in existing time zones. For more information about the time zone definition structure in EWS in Exchange 2010, see TimeZoneDefinition in the Microsoft Exchange Server 2010 Web Services SDK.

By using the time zone definitions that are supported by the Exchange server (that is, the definitions that correspond to the time zone registry keys that exist in the Windows Server registry of the Exchange server), client applications can achieve greater time zone accuracy and consistency.

A client application that uses the EWS Managed API can use the Microsoft .NET Framework 3.5 TimeZoneInfo class to get time zone definitions that are compatible with the time zone format of the Exchange server. The following code example shows how to get the time zone definition for the Eastern Standard Time time zone by using the .NET Framework 3.5 TimeZoneInfo class.

TimeZoneInfo tzinfo = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");

A client application that uses the EWS autogenerated proxy can use the GetServerTimeZones operation to get time zone definitions that are supported by the Exchange server. The following code example shows how to get the full time zone definition for the Eastern Standard Time time zone. This example assumes that esb is a valid ExchangeServiceBinding.

// Get the complete definition for the Eastern Standard Time time zone.
GetServerTimeZonesType gstzRequest = new GetServerTimeZonesType();
gstzRequest.Ids = new string[] { "Eastern Standard Time" };
gstzRequest.ReturnFullTimeZoneData = true;
gstzRequest.ReturnFullTimeZoneDataSpecified = true;
GetServerTimeZonesResponseType gstzResponse = esb.GetServerTimeZones(gstzRequest);
GetServerTimeZonesResponseMessageType responseMsg = gstzResponse.ResponseMessages.Items[0] as GetServerTimeZonesResponseMessageType;

// If the operation succeeded, save the time zone definition to ESTTimeZoneDefinition.
if (responseMsg.ResponseClass == ResponseClassType.Success)
{
    TimeZoneDefinitionType ESTTimeZoneDefinition = responseMsg.TimeZoneDefinitions.TimeZoneDefinition[0];
}
else
{
    throw new Exception("GetServerTimeZonesType() failed.");
}

The following example shows the XML that is sent by using the GetServerTimeZones operation to request the full definition for the Eastern Standard Time time zone.

<?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:m="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2010"/>
  </soap:Header>
  <soap:Body>
    <m:GetServerTimeZones ReturnFullTimeZoneData="true">
      <m:Ids>
        <t:Id>Eastern Standard Time</Id>
      </m:Ids>
    </m:GetServerTimeZones>
  </soap:Body>
</soap:Envelope>

The following example shows the XML response that is returned when the GetServerTimeZones operation is used to request the full definition for the Eastern Standard Time time zone.

<?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="639" MinorBuildNumber="21" 
                         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:GetServerTimeZonesResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                                  xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:GetServerTimeZonesResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:TimeZoneDefinitions>
            <t:TimeZoneDefinition Name="(GMT-05:00) Eastern Time (US &amp; Canada)" Id="Eastern Standard Time">
              <t:Periods>
                <t:Period Bias="PT5H" Name="Standard" Id="trule:Microsoft/Registry/Eastern Standard Time/2006-Standard"/>
                <t:Period Bias="PT4H" Name="Daylight" Id="trule:Microsoft/Registry/Eastern Standard Time/2006-Daylight"/>
                <t:Period Bias="PT5H" Name="Standard" Id="trule:Microsoft/Registry/Eastern Standard Time/2007-Standard"/>
                <t:Period Bias="PT4H" Name="Daylight" Id="trule:Microsoft/Registry/Eastern Standard Time/2007-Daylight"/>
              </t:Periods>
              <t:TransitionsGroups>
                <t:TransitionsGroup Id="0">
                  <t:RecurringDayTransition>
                    <t:To Kind="Period">trule:Microsoft/Registry/Eastern Standard Time/2006-Daylight</t:To>
                    <t:TimeOffset>PT2H</t:TimeOffset>
                    <t:Month>4</t:Month>
                    <t:DayOfWeek>Sunday</t:DayOfWeek>
                    <t:Occurrence>1</t:Occurrence>
                  </t:RecurringDayTransition>
                  <t:RecurringDayTransition>
                    <t:To Kind="Period">trule:Microsoft/Registry/Eastern Standard Time/2006-Standard</t:To>
                    <t:TimeOffset>PT2H</t:TimeOffset>
                    <t:Month>10</t:Month>
                    <t:DayOfWeek>Sunday</t:DayOfWeek>
                    <t:Occurrence>-1</t:Occurrence>
                  </t:RecurringDayTransition>
                </t:TransitionsGroup>
                <t:TransitionsGroup Id="1">
                  <t:RecurringDayTransition>
                    <t:To Kind="Period">trule:Microsoft/Registry/Eastern Standard Time/2007-Daylight</t:To>
                    <t:TimeOffset>PT2H</t:TimeOffset>
                    <t:Month>3</t:Month>
                    <t:DayOfWeek>Sunday</t:DayOfWeek>
                    <t:Occurrence>2</t:Occurrence>
                  </t:RecurringDayTransition>
                  <t:RecurringDayTransition>
                    <t:To Kind="Period">trule:Microsoft/Registry/Eastern Standard Time/2007-Standard</t:To>
                    <t:TimeOffset>PT2H</t:TimeOffset>
                    <t:Month>11</t:Month>
                    <t:DayOfWeek>Sunday</t:DayOfWeek>
                    <t:Occurrence>1</t:Occurrence>
                  </t:RecurringDayTransition>
                </t:TransitionsGroup>
              </t:TransitionsGroups>
              <t:Transitions>
                <t:Transition>
                  <t:To Kind="Group">0</t:To>
                </t:Transition>
                <t:AbsoluteDateTransition>
                  <t:To Kind="Group">1</t:To>
                  <t:DateTime>2007-01-01T00:00:00</t:DateTime>
                </t:AbsoluteDateTransition>
              </t:Transitions>
            </t:TimeZoneDefinition>
          </m:TimeZoneDefinitions>
        </m:GetServerTimeZonesResponseMessage>
      </m:ResponseMessages>
    </m:GetServerTimeZonesResponse>
  </s:Body>
</s:Envelope>

A client application can specify a session time zone when establishing the connection to EWS. The session time zone is used to do the following:

• Provide time zone offsets to DateTime properties that have no offsets specified.

• Account for time changes when expanding recurring appointments.

• Scope the time zone of all-day appointments.

• Scope the time zone of task completion dates.

A client application that uses the EWS Managed API can specify the session time zone when it instantiates the ExchangeService object. The following code example shows how to use the EWS Managed API to specify Eastern Standard Time as the time zone to assign to DateTime properties of objects that are created or retrieved, in cases where no overriding time zone value is specified for a DateTime property.

ExchangeService serviceEST = new ExchangeService(ExchangeVersion.Exchange2010, 
                                                 TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time"));

A client application that uses the EWS auto-generated proxy can set the TimeZoneContext property on the ExchangeServiceBinding object to specify the time zone of the session. The following code example shows how to get the time zone definition for the Eastern Standard Time time zone and set the TimeZoneContext property on the ExchangeServiceBinding object. This example assumes that esb is a valid ExchangeServiceBinding.

// Get the complete definition for the Eastern Standard Time time zone.
GetServerTimeZonesType gstzRequest = new GetServerTimeZonesType();
gstzRequest.Ids = new string[] { "Eastern Standard Time" };
gstzRequest.ReturnFullTimeZoneData = true;
gstzRequest.ReturnFullTimeZoneDataSpecified = true;
GetServerTimeZonesResponseType gstzResponse = esb.GetServerTimeZones(gstzRequest);
GetServerTimeZonesResponseMessageType responseMsg = gstzResponse.ResponseMessages.Items[0] as GetServerTimeZonesResponseMessageType;

// Set the TimeZoneContext property on the ExchangeServiceBinding object.
if (responseMsg.ResponseClass == ResponseClassType.Success)
{
    TimeZoneContextType tzContext = new TimeZoneContextType();
    tzContext.TimeZoneDefinition = responseMsg.TimeZoneDefinitions.TimeZoneDefinition[0];
    esb.TimeZoneContext = tzContext;
}
else
{
    throw new Exception("GetServerTimeZones() failed.");
}

A client application that uses the EWS Managed API can set the StartTimeZone property to specify the time zone of the Start property and ReminderDueBy property of a calendar item. The StartTimeZone property value will also be applied as the time zone of the End property of a calendar item if the client does not set the EndTimeZone property on the calendar item. Therefore, it is only necessary to set the EndTimeZone property on a calendar item if the time zone of the end time is different than the time zone of the start time. For example, to create a calendar item that represents a flight that starts in one time zone and ends in another, the client would set both the StartTimeZone property and the EndTimeZone property.

The following code shows how to set the start time zone on an Appointment object to Central Standard Time and the end time zone to Eastern Standard Time by using the EWS Managed API.

// Create a calendar item.
Appointment appt = new Appointment(service);

// TODO: Set properties on the calendar item.

// Set the start time, start time zone, end time, and end time zone.
appt.Start = new DateTime(2010, 2, 12, 10, 0, 0, DateTimeKind.Unspecified);
appt.StartTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time");
appt.End = new DateTime(2010, 2, 12, 11, 0, 0, DateTimeKind.Unspecified);
appt.EndTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");

A client application that uses the EWS autogenerated proxy can set the StartTimeZone property to specify the time zone of the Start property and ReminderDueBy property of a calendar item. As explained earlier (for the EWS Managed API), the StartTimeZone property value will also be applied as the time zone of the End property of a calendar item if the client does not set the EndTimeZone property on the calendar item. To specify a different time zone for the End property of a calendar item, the client must set the EndTimeZone property.

The following code shows how to scope the DateTime properties on a CalendarItemType object to the Central Standard Time time zone by using the autogenerated proxy.

// Create a calendar item.
CalendarItemType myAppt = new CalendarItemType();

// TODO: Set properties on the calendar item.

// Get the time zone definition for Central Standard Time.
GetServerTimeZonesType gstzRequest = new GetServerTimeZonesType();
gstzRequest.Ids = new string[] { "Central Standard Time" };
gstzRequest.ReturnFullTimeZoneData = true;
gstzRequest.ReturnFullTimeZoneDataSpecified = true;
GetServerTimeZonesResponseType gstzResponse = esb.GetServerTimeZones(gstzRequest);
GetServerTimeZonesResponseMessageType responseMsg = 
gstzResponse.ResponseMessages.Items[0] as GetServerTimeZonesResponseMessageType;
TimeZoneDefinitionType[] timezones = 
responseMsg.TimeZoneDefinitions.TimeZoneDefinition;
TimeZoneDefinitionType tzdt = timezones[0];

// Set the start time, end time, and start time zone property on the calendar item.
// Specify DateTimeKind.Unspecified when setting Start and End, so that the server will apply time zone 
// offsets by using the value of StartTimeZone.
myAppt.Start = new DateTime(2010, 02, 12, 10, 0, 0, DateTimeKind.Unspecified);
myAppt.StartSpecified = true;
myAppt.End = dtStart.AddHours(1);
myAppt.EndSpecified = true;
myAppt.StartTimeZone = tzdt;

The following example shows an XML request that creates a calendar item and specifies Central Standard Time as the time zone of the DateTime properties.

<soap:Body>
  <CreateItem SendMeetingInvitations="SendToAllAndSaveCopy">
    <Items>
      <CalendarItem>
        <Subject>Another Appt</Subject>
        <Body BodyType="Text">My Appt</Body>
        <Start>2010-02-12T10:00:00</Start>
        <End>2010-02-12T11:00:00</End>
        <Location>My Location</Location>
        <StartTimeZone Id="Central Standard Time" Name="(GMT-06:00) Central Time (US &amp; Canada)">...</StartTimeZone>
      </CalendarItem>
    </Items>
  </CreateItem>
</soap:Body>