• Article

Time zones in the EWS Managed API 2.0

Find general information about working with time zones in applications that use the EWS Managed API.

Last modified: January 30, 2014

Applies to: EWS Managed API | Exchange Server 2007 Service Pack 1 (SP1) | Exchange Server 2010

Note: This content applies to the EWS Managed API 2.0 and earlier versions. For the latest information about the EWS Managed API, see Web services in Exchange.

If your application uses items that have DateTime properties, such as calendar items or task items, it is important for you to understand how the Exchange Web Services (EWS) Managed API handles time zones. EWS stores all date/time strings in Coordinated Universal Time (UTC). This is because UTC does not follow daylight saving time and therefore can serve as an absolute point of reference for date/time. In a practical sense, however, UTC is not very useful as a time zone context within an application. For example, a meeting that is scheduled for next Tuesday at 2:00 P.M. UTC might be confusing, because most people are not accustomed to converting between UTC and local time. Fortunately, the EWS Managed API provides a means for you to specify the time zone that will be used when you create, retrieve, synchronize, and update items that have DateTime properties. By specifying time zone, you can use the time zone or time zones that make sense for your application, and the fact that EWS stores date/time strings in UTC becomes transparent to users of your application.

Determining time zone

Whether a time zone is specified when the ExchangeService object is instantiated, and whether the StartTimeZone property and EndTimeZone property (supported in versions of Exchange starting with Exchange 2010) are set, will determine the time zone of DateTime properties that belong to items that are created, updated, and retrieved by using the EWS Managed API. 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

When using the EWS Managed API against Exchange 2007 SP1:

  • When creating or updating a calendar item, DateTime properties will be scoped to UTC.

  • When creating or updating a non-calendar item, DateTime properties will be scoped to the computer's local time zone.

  • When retrieving (that is, getting, finding, or synchronizing) items, DateTime properties will be scoped to the computer's local time zone.

When using the EWS Managed API against versions of Exchange starting with Exchange 2010:

  • 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.

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 in Exchange 2007 SP1:

  • The time zone of all DateTime properties on the appointment will be set to the time zone specified by the StartTimeZone property on the appointment. Setting the EndTimeZone property on the appointment will cause an exception to be thrown.

When creating or updating a calendar item in versions of Exchange starting with Exchange 2010:

  • The time zone of the Start property and ReminderDueBy property on the appointment will be set to the time zone specified by the StartTimeZone property on the appointment. The time zone of the End property on the appointment will be set 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 in Exchange 2007 SP1:

  • The time zone of all DateTime properties on the appointment will be set to the time zone specified by the StartTimeZone property on the appointment. Setting the EndTimeZone property on the appointment will cause an exception to be thrown.

When creating or updating a calendar item in versions of Exchange starting with Exchange 2010:

  • The time zone of the Start property and ReminderDueBy property on the appointment will be set to the time zone specified by the StartTimeZone property on the appointment. The time zone of the End property on the appointment will be set to the time zone specified by the 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.