Partager via

  • Article

Updating the time zone for items by using the EWS Managed API 2.0

Last modified: October 13, 2012

Applies to: EWS Managed API | 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.

You can use the Microsoft Exchange Web Services (EWS) Managed API to update the time zone for items. When you update the time zone for an item, you can also change the start time of the item, or you can update the time zone for an item without changing the item’s start time.

Note

For more information about time zones, see Time zones in the EWS Managed API 2.0.

To change the time zone for an appointment and update the start time accordingly

  1. Bind to the existing appointment by using its unique identifier. The following code shows how to bind to an existing appointment, provide it with connection configuration information by using an ExchangeService object named service, and request a specific subset of properties, including the DateTime properties and the time zone properties. The ItemId has been shortened to preserve readability. For the purpose of this example, assume that the service object is scoped to the Pacific Standard Time (PST) time zone.

    Appointment appt = Appointment.Bind(service, new ItemId("AAMkA="), new PropertySet(BasePropertySet.IdOnly, AppointmentSchema.Start, AppointmentSchema.ReminderDueBy, AppointmentSchema.End, AppointmentSchema.StartTimeZone, AppointmentSchema.EndTimeZone, AppointmentSchema.TimeZone));

  2. Examine the initial value of the Start property and StartTimeZone property. Because the appointment was retrieved by using an ExchangeService object that is scoped to PST, the 7 A.M. start time for this appointment is expressed in PST, even though the appointment's StartTimeZone is EST. For more information about the rules that determine the time zone of DateTime properties when you retrieve items, see Specifying the time zone when retrieving items by using the EWS Managed API 2.0.

    Console.WriteLine(appt.Start); // 1/1/2009 7 A.M. (PST)
Console.WriteLine(appt.StartTimeZone); // EST

  3. Update the StartTimeZone property and the EndTimeZone property on the appointment. The following code shows how to set these properties to Central Standard Time (CST).

    appt.StartTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time");
appt.EndTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time");

  4. Save the updated appointment, as shown in the following code.

    appt.Update(ConflictResolutionMode.AlwaysOverwrite);

  5. Bind to the updated appointment and examine the value of the Start property and StartTimeZone property, as shown in the following code.

    appt.Load(new PropertySet(BasePropertySet.IdOnly, AppointmentSchema.Start, AppointmentSchema.ReminderDueBy, AppointmentSchema.End, AppointmentSchema.StartTimeZone, AppointmentSchema.EndTimeZone, AppointmentSchema.TimeZone));
Console.WriteLine(appt.Start); // 1/1/2009 8 A.M.(PST)
Console.WriteLine(appt.StartTimeZone); // CST

    Because the appointment time zone was changed from EST to CST, without updating any of the DateTime properties, the meeting has been moved forward by one hour (the difference between EST and CST), as shown in the following table.

    Start time

    Start time zone

    Start time (PST)

    Values Before Update

    10 a.m.

    EST

    7 a.m. PST

    Values After Update

    10 a.m.

    CST

    8 a.m. PST

To change the time zone for an appointment without changing the start time

  1. Bind to the existing appointment by using its unique identifier. The following code shows how to bind to an existing appointment, provide it with connection configuration information by using an ExchangeService object named service, and request a specific subset of properties, including the DateTime properties and the time zone properties. The ItemId has been shortened to preserve readability. For the purpose of this example, assume that the service object is scoped to the Pacific Standard Time (PST) time zone.

    Appointment appt = Appointment.Bind(service, new ItemId("AAMkA="), new PropertySet(BasePropertySet.IdOnly, AppointmentSchema.Start, AppointmentSchema.ReminderDueBy, AppointmentSchema.End, AppointmentSchema.StartTimeZone, AppointmentSchema.EndTimeZone, AppointmentSchema.TimeZone));

  2. Examine the initial value of the Start property and StartTimeZone property. Because the appointment was retrieved by using an ExchangeService object that is scoped to the PST time zone, the 9 A.M. start time for this appointment is expressed in PST, even though the appointment's StartTimeZone is CST. For more information about the rules that determine the time zone of DateTime properties when you retrieve items, see Specifying the time zone when retrieving items by using the EWS Managed API 2.0.

    Console.WriteLine(appt.Start); // 1/1/2009 9 A.M. (PST)
Console.WriteLine(appt.StartTimeZone); // CST

  3. Update the StartTimeZone property and the EndTimeZone property on the appointment. The following code shows how to set these properties both to Eastern Standard Time (EST).

    appt.StartTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");
appt.EndTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");

  4. Because the appointment is being moved from the CST time zone to the EST time zone, you must also update the Start, End, and ReminderDueBy properties, if you want the appointment to occur at the same time before and after the update. The following code shows how to increment each of these times by one hour (the time difference between CST and EST).

    appt.Start = appt.Start.AddHours(1);
appt.ReminderDueBy = appt.ReminderDueBy.AddHours(1);
appt.End = appt.End.AddHours(1);

  5. Save the updated appointment, as shown in the following code.

    appt.Update(ConflictResolutionMode.AlwaysOverwrite);

  6. Bind to the updated appointment and examine the value of the Start property and StartTimeZone property, as shown in the following code.

    appt.Load(new PropertySet(BasePropertySet.IdOnly, AppointmentSchema.Start, AppointmentSchema.ReminderDueBy, AppointmentSchema.End, AppointmentSchema.StartTimeZone, AppointmentSchema.EndTimeZone, AppointmentSchema.TimeZone));
Console.WriteLine(appt.Start); // 1/1/2009 9 A.M.(PST)
Console.WriteLine(appt.StartTimeZone); // EST

    Because the appointment time zone was changed from EST to CST, and each DateTime property was adjusted by one hour (the time difference between CST and EST), the meeting time is unchanged, as shown in the following table.

    Start time

    Start time zone

    Start time (PST)

    Values Before Update

    11 a.m.

    CST

    9 a.m. PST

    Values After Update

    12 p.m.

    EST

    9 a.m. PST

Compiling the code

For information about compiling this code, see Getting started with the EWS Managed API 2.0.

Robust programming

  • Write appropriate error handling code for common search errors.

  • Review the client request XML that is sent to the Exchange server.

  • Review the server response XML that is sent from the Exchange server.

  • Set the service binding as shown in Setting the Exchange service URL by using the EWS Managed API 2.0. Do not hard code URLs because if mailboxes move, they might be serviced by a different Client Access server. If the client cannot connect to the service, retry setting the binding by using the AutodiscoverUrl(String) method.

  • Set the target Exchange Web Services schema version by setting the requestedServerVersion parameter of the ExchangeService constructor. For more information, see Versioning EWS requests by using the EWS Managed API 2.0.

Security

  • Use HTTP with SSL for all communication between client and server.

  • Always validate the server certificate that is used for establishing the SSL connections. For more information, see Validating X509 certificates by using the EWS Managed API 2.0.

  • Do not include user names and passwords in trace files.

  • Verify that Autodiscover lookups that use HTTP GET to find an endpoint always prompt for user confirmation; otherwise, they should be blocked.