Edit

Time zones and EWS in Exchange

  • Article

Find out how time zones work with the EWS Managed API and EWS in Exchange.

Time zones aren't something that most people give much thought to. However, they're an important concept when specifying dates and times using the EWS Managed API or EWS. Mishandling time zones in an EWS Managed API or EWS application can yield unexpected results. Handling time zones properly is easy, as long as you know how.

Handling time zones in the EWS Managed API

If you're using the EWS Managed API, time zones are, for the most part, handled for you automatically. Without any explicit action on your part, the API uses the local time zone of the client computer and handles all necessary conversions behind the scenes. This is great when that's the desired effect, but you have other options.

One option is setting the ExchangeService.TimeZone property. This property controls the time zone for all requests executed by the EWS Managed API. This property is read-only; the only way to set it is via the class constructor. If you use either the ExchangeService(System.TimeZoneInfo) or the ExchangeService(ExchangeVersion, System.TimeZoneInfo) constructor, you can specify a specific time zone as a System.TimeZoneInfo object. If you use one of the other constructors that do not take a TimeZoneInfo object as a parameter, the ExchangeService class sets the TimeZone property to the current time zone of the client computer.

Whether you set a specific time zone or leave it as the time zone of the client computer, all dates and times are expressed in the time zone represented by the TimeZone property. The EWS Managed API exposes all date/time properties as System.DateTime structures. So if you set any date/time properties, be mindful that the time you specify is interpreted according to the DateTime.Kind property value on the DateTime object. If the value of the Kind property is set to Unspecified, the value of the DateTime is interpreted as being in the time zone specified by the TimeZone property. If you're reading date/time properties, all DateTime properties are expressed in that time zone.

If you are creating new appointments or meetings or updating existing appointments or meetings, you have the ability to override the time zone specified in the TimeZone for new Appointment objects. However, exactly what you can override depends on the EWS schema version you are targeting. For all values of the ExchangeService.RequestedServerVersion property, you can set the Appointment.StartTimeZone to use a specific time zone for that appointment or meeting. If you're using a value for the ExchangeService.RequestedServerVersion property greater than Exchange2007_SP1, you can also set the Appointment.EndTimeZone property, allowing you to specify a time zone for the Appointment.End property. However, bear in mind that these properties only affect the interpretation of the date/time for the create request. If you retrieve the appointment, the start and end times will still be expressed in the time zone specified by the TimeZone property.

If you are updating existing appointments or meetings, you can change the time zone for an Appointment object by setting the StartTimeZone property and/or the EndTimeZone property. Doing so will cause the applicable times to shift accordingly. If you've set the ExchangeService.RequestedServerVersion to Exchange2007_SP1, you cannot set the EndTimeZone property; the value of the StartTimeZone property will be used in its place.

Table 1. Time zone properties in the EWS Managed API

Time zone property Minimum server request version Description
TimeZone
Exchange2007_SP1
If not set via the constructor for the ExchangeService class, this property is set to the time zone of the client computer. All DateTime properties when creating items and when retrieving existing items are expressed in this time zone. This time zone can be overridden in create requests for appointments and meetings by setting the Appointment.StartTimeZone and/or the Appointment.EndTimeZone property. If not overridden by the Appointment.StartTimeZone property, this time zone is considered the creation time zone for appointments and meetings.
StartTimeZone
Exchange2007_SP1
If set on new Appointment objects, this time zone is used to interpret the Appointment.Start and Appointment.ReminderDueBy properties. This time zone is also considered the creation time zone for the Appointment object.
When retrieving existing items, this property is informational only. The values of DateTime properties on existing appointment are always expressed in the time zone specified by the ExchangeService.TimeZone property.
EndTimeZone
Exchange2010
If set on new Appointment objects, this time zone is used to interpret the Appointment.End property.
When retrieving existing items, this property is informational only. The values of DateTime properties on existing appointment are always expressed in the time zone specified by the ExchangeService.TimeZone property.

Handling time zones in EWS

If you're using EWS, time zones aren't handled for you automatically, and things are a bit more complicated. How time zones impact EWS requests and responses depends on a number of factors:

The time zone specified in the value of dateTime elements can take three forms. You can read all the details in XML Schema Part 2: Datatypes Second Edition, but to paraphrase:

  • Universal Coordinated Time (UTC): Specified by 'Z'. For example, 2014-06-06T19:00:00.000Z

  • Specific time zone: Specified by '+' or '-' followed by hours and minutes. For example, 2014-06-06T19:00:00.000-08:00

  • No time zone: Specified by the absence of any time zone. For example, 2014-06-06T19:00:00.000

If a time zone is present in a dateTime value (either UTC or a specific time zone), that value is always interpreted as that time zone. If no time zone is present, then the interpretation of the value depends on the specific combination of the other time-zone related elements.

Table 2. Time zone elements in EWS and their effects

RequestServerVersion TimeZoneContext present? MeetingTimeZone, StartTimeZone, or EndTimeZone present (CalendarItem and MeetingRequest only)? dateTime in UTC dateTime in specific time zone dateTime with no time zone Appointment and meeting creation time zone
Exchange2007_SP1
Yes
Yes ( MeetingTimeZone )
Interpreted as UTC
Interpreted as the time zone indicated in the value
Elements within the CalendarItem or MeetingRequest element that contains the MeetingTimeZone element are interpreted as the time zone in the MeetingTimeZone element, all others interpreted as UTC
Time zone in MeetingTimeZone element
Exchange2007_SP1
Yes
No
Interpreted as UTC
Interpreted as the time zone indicated in the value
Interpreted as UTC
UTC
Exchange2007_SP1
No
Yes ( MeetingTimeZone )
Interpreted as UTC
Interpreted as the time zone indicated in the value
Elements within the CalendarItem or MeetingRequest element that contains the MeetingTimeZone element are interpreted as the time zone in the MeetingTimeZone element, all others interpreted as UTC
Time zone in MeetingTimeZone element
Exchange2007_SP1
No
No
Interpreted as UTC
Interpreted as the time zone indicated in the value
Interpreted as UTC
UTC
Exchange2010 and later
Yes
Yes ( StartTimeZone and/or EndTimeZone )
Interpreted as UTC
Interpreted as the time zone indicated in the value
If the StartTimeZone element is present, the value of the Start and ReminderDueBy elements are interpreted as the time zone in the StartTimeZone element. Otherwise, the value of those elements are interpreted as the time zone in the TimeZoneContext element.
If the EndTimeZone element is present, the value of the Start element is interpreted as the time zone in the EndTimeZone element. Otherwise, the value of the End element is interpreted as the time zone in the TimeZoneContext element.
Elements outside the CalendarItem or MeetingRequest are interpreted as the time zone in the TimeZoneContext element.
Time zone in the StartTimeZone element if present, time zone in the TimeZoneContext element if not
Exchange2010 and later
Yes
No
Interpreted as UTC
Interpreted as the time zone indicated in the value
Interpreted as the time zone in the TimeZoneContext element
Time zone in the TimeZoneContext element
Exchange2010 and later
No
Yes ( StartTimeZone and/or EndTimeZone )
Interpreted as UTC
Interpreted as the time zone indicated in the value
If the StartTimeZone element is present, the value of the Start and ReminderDueBy elements are interpreted as the time zone in the StartTimeZone element. Otherwise, the value of those elements are interpreted as UTC.
If the EndTimeZone element is present, the value of the Start element is interpreted as the time zone in the EndTimeZone element. Otherwise, the value of the End element is interpreted as UTC.
Elements outside the CalendarItem or MeetingRequest are interpreted as UTC.
Time zone in the StartTimeZone element if present, UTC if not
Exchange2010 and later
No
No
Interpreted as UTC
Interpreted as the time zone indicated in the value
Interpreted as UTC
UTC

When interpreting responses from the server, you should always check the value of each element and interpret the value accordingly. Exchange will always include a time zone (either UTC or a specific time zone) in the value.

Additional time zone considerations when creating appointments and meetings

When you create an appointment or meeting, the time zone that applies to the start time is considered the creation time zone for the appointment. In addition to controlling how the date/times are interpreted when an appointment or meeting is created, the creation time zone has the following effects on the item:

  • If the item is an all-day event, it might display in an unexpected way if viewed from a client that is using a different time zone than the creation time zone. This is because when an all-day event is created, the start and end time of all-day events are adjusted to midnight of the creation time zone. That time will show as a time other than midnight in a different time zone, so the item may appear to span extra days. Because of this, we recommend that you use the time zone configured for the user's primary calendaring client to create all-day events when possible.

  • If the item is a meeting, the creation time zone will be displayed in the Outlook information bar on the meeting requests received by the attendees, if that time zone differs from the time zone of their client.

In this section

See also