Working with Time Zones in Exchange 2010 Exchange Web Services
Last modified: February 16, 2010
Applies to: Exchange Server 2010
In this article
Time Zone Changes in EWS in Exchange 2010
EWS Time Zone Logic in Exchange 2010
EWS Time Zone Best Practices in Exchange 2010
By Kim Brandl
Significant changes have been made to Exchange Web Services (EWS) in Microsoft Exchange Server 2010 that affect how you work with time zones. This article describes these changes and suggests best practices for working with time zones by using EWS with Exchange 2010.
Note
The information in this article applies to using the EWS autogenerated proxy or the EWS Managed API with Exchange 2010. For more information about working with time zones by using the EWS Managed API, see Time Zones and Working with Time Zones in the Microsoft Exchange Web Services Managed API SDK.
Time Zone Changes in EWS in Exchange 2010
EWS in Exchange 2010 introduces a number of changes that affect how client applications work with time zones, including the following:
A new time zone definition structure.
The ability for client applications to get well-known Windows time zone definitions from the Exchange server.
The ability for client applications to specify a session time zone.
The ability for client applications to override the session time zone for specific DateTime properties on calendar items.
New Time Zone Definition Structure
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.
Getting Well-Known Windows Time Zone Definitions from the Exchange Server
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");
Note
To get a collection of all time zone definitions from the local registry of the client that are compatible with the time zone format of the Exchange server, use the TimeZoneInfo.GetSystemTimeZones() method. For more information, see Getting Time Zone Definitions in the Microsoft Exchange Web Services Managed API SDK.
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.");
}
Note
To get a collection of all time zone definitions that are compatible with the time zone format of the Exchange server, do not set the Ids property on the GetServerTimeZonesType object.
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 & 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>
Specifying a Session Time Zone
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.");
}
Note
Setting the TimeZoneContext property on the ExchangeServiceBinding object specifies the TimeZoneContext element in the Simple Object Access Protocol (SOAP) header. For more information about the TimeZoneContext element in the SOAP header, see TimeZoneContext in the Microsoft Exchange Server 2010 Web Services SDK.
Overriding the Session Time Zone for Specific DateTime Properties on Calendar Items
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");
Note
If DateTimeKind.Unspecified is specified when setting the DateTime properties on a calendar item (as shown in the previous example), the server will apply time zone offsets to the DateTime property values as specified by the StartTimeZone and EndTimeZone properties.
If DateTimeKind.Utc is specified when setting the DateTime properties on a calendar item, the server will ignore the values of StartTimeZone and EndTimeZone and will not apply time zone offsets to the DateTime property values.
Specifying DateTimeKind.Local when setting the DateTime properties on a calendar item is not recommended.
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 & Canada)">...</StartTimeZone>
</CalendarItem>
</Items>
</CreateItem>
</soap:Body>
EWS Time Zone Logic in Exchange 2010
For client applications that use the EWS Managed API, whether a time zone is specified when the ExchangeService object is instantiated, and whether the StartTimeZone property and EndTimeZone property are set, will determine the time zone offset for DateTime properties that do not specify an offset on items that are created, updated, and retrieved. The following table describes the possible scenarios based on these two factors.
Is a time zone specified when ExchangeService is instantiated? |
For Appointment objects, are the StartTimeZone and EndTimeZone properties set? |
Result |
|---|---|---|
No |
No |
For all types of operations (that is, create, update, get, find, synchronize) and all object types (that is, calendar items and non-calendar items), DateTime properties will be scoped to the computer's local time zone (that is, TimeZoneInfo.Local). |
Yes |
No |
For all types of operations (that is, create, update, get, find, synchronize) and all object types (that is, calendar items and non-calendar items), DateTime properties will be scoped to the time zone specified when the ExchangeService object is instantiated. |
Yes |
Yes |
When creating or updating a calendar item, the Start property and the ReminderDueBy property on the appointment will be scoped to the time zone specified by the StartTimeZone property on the appointment. If the EndTimeZone property is not specified, the End property on the appointment will also be scoped to the time zone specified by the StartTimeZone property on the appointment. If the EndTimeZone property is specified, the End property on the appointment will be scoped to the time zone specified by EndTimeZone property on the appointment. When creating or updating a non-calendar item, all DateTime properties will be scoped to the time zone specified when the ExchangeService object is instantiated. When retrieving any type of item, all DateTime properties will be scoped to the time zone specified when the ExchangeService object is instantiated. |
No |
Yes |
When creating or updating a calendar item, the Start property and the ReminderDueBy property on the appointment will be scoped to the time zone specified by the StartTimeZone property on the appointment. If the EndTimeZone property is not specified, the End property on the appointment will also be scoped to the time zone specified by the StartTimeZone property on the appointment. If the EndTimeZone property is specified, the End property on the appointment will be scoped to the time zone specified by EndTimeZone property on the appointment. When creating or updating a non-calendar item, all DateTime properties will be scoped to the computer's local time zone. When retrieving any type of item, all DateTime properties will be scoped to the computer's local time zone. |
For client applications that use pure XML or the EWS autogenerated proxy, whether the TimeZoneContext element is specified in the SOAP header, and whether the StartTimeZone property and EndTimeZone property are set, will determine the time zone offset for DateTime properties that do not specify an offset on items that are created, updated, and retrieved. The following table describes the possible scenarios based on these two factors.
Is the TimeZoneContext element specified in the SOAP header? |
For calendar items, are the StartTimeZone and EndTimeZone properties set? |
Result |
|---|---|---|
No |
No |
For all types of operations (that is, create, update, get, find, synchronize) and all object types (that is, calendar items and non-calendar items), DateTime properties will be scoped to Coordinated Universal Time (UTC). |
Yes |
No |
For all types of operations (that is, create, update, get, find, synchronize) and all object types (that is, calendar items and non-calendar items), DateTime properties will be scoped to the time zone specified by the TimeZoneContext element in the SOAP header. |
Yes |
Yes |
When creating or updating a calendar item, the Start property and the ReminderDueBy property on the calendar item will be scoped to the time zone specified by the StartTimeZone property on the calendar item. If the EndTimeZone property is not specified, the End property on the calendar item will also be scoped to the time zone specified by the StartTimeZone property on the calendar item. If the EndTimeZone property is specified, the End property on the calendar item will be scoped to the time zone specified by EndTimeZone property on the calendar item. When creating or updating a non-calendar item, all DateTime properties will be scoped to the time zone specified by the TimeZoneContext element in the SOAP header. When retrieving any type of item, all DateTime properties will be scoped to the time zone specified by the TimeZoneContext element in the SOAP header. |
No |
Yes |
When creating or updating a calendar item, the Start property and the ReminderDueBy property on the calendar item will be scoped to the time zone specified by the StartTimeZone property on the calendar item. If the EndTimeZone property is not specified, the End property on the calendar item will also be scoped to the time zone specified by the StartTimeZone property on the calendar item. If the EndTimeZone property is specified, the End property on the calendar item will be scoped to the time zone specified by EndTimeZone property on the calendar item. When creating or updating a non-calendar item, all DateTime properties will be scoped to UTC. When retrieving any type of item, all DateTime properties will be scoped to UTC. |
EWS Time Zone Best Practices in Exchange 2010
When working with time zones in Exchange 2010, we recommend that EWS client applications adhere to the following best practices:
Use 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).
Always set the session time zone for the Exchange service.
When necessary, use the StartTimeZone property and EndTimeZone property to override the session time zone for the start time, reminder due by time, and end time of calendar items.
If a calendar item’s starting time zone and ending time zone is the same, set only the StartTimeZone property on the calendar item. (The StartTimeZone property value will also be applied to the End property on a calendar item when the EndTimeZone property is not specified.)
If a calendar item’s starting time zone and ending time zone are different, set the StartTimeZone property to specify the time zone for the Start and ReminderDueBy properties, and the EndTimeZone property to specify the time zone for the End property.
Do not set the MeetingTimeZone property on calendar items; this property is deprecated in Exchange 2010 and setting it will result in an error.
Whenever possible, use the EWS Managed API instead of the autogenerated proxy or plain XML to interface with EWS. The EWS Managed API requires significantly less code than the autogenerated proxy or plain XML and is much easier to use.
See Also