Specifying the time zone when retrieving items by using the EWS Managed API 2.0

Last modified: September 12, 2013

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 Exchange Web Services (EWS) Managed API to retrieve (that is, get, find, or synchronize) items that have DateTime properties. This topic explains how the time zone of DateTime properties is determined when you retrieve items by using the EWS Managed API.

Note

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

To retrieve an item with DateTime properties scoped to the local time zone

• Instantiate the ExchangeService object without specifying the time zone, as shown in the following code. If you do not specify a time zone, the EWS Managed API will use the computer's local time zone as the time zone context for all DateTime properties of items that are retrieved by using the ExchangeService.

  ExchangeService service = new ExchangeService();
  

To retrieve an item with DateTime properties scoped to a non-local time zone

• Specify the time zone when you instantiate the ExchangeService object that will be used to retrieve the item. The time zone that is specified when the ExchangeService object is instantiated is the time zone context for all DateTime properties of items that are retrieved by using the ExchangeService. The following code shows how to specify the Eastern Standard Time time zone when you instantiate the ExchangeService object.

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

Example

Retrieving an appointment in different time zones

The following code example shows how to create an appointment with Start, End, and ReminderDueBy properties in Eastern Standard Time. It then shows how to retrieve that appointment with Start, End, and ReminderDueBy properties expressed in local time (Pacific Standard Time), how to retrieve that appointment with Start, End, and ReminderDueBy properties expressed in Eastern Standard Time, and how to retrieve that appointment with Start, End, and ReminderDueBy properties expressed in Central Standard Time. The ItemId attribute has been shortened to preserve readability.

//*************************************************
//* Create the Appointment in Eastern Standard Time.
//*************************************************

// Instantiate the ExchangeService object and specify the Eastern Standard Time time zone. 
ExchangeService serviceEST = new ExchangeService(TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time"));

// Set the credentials for the ExchangeService, by specifying the user name, password, and domain, and use Autodiscover to set the Url.
serviceEST.Credentials = new WebCredentials("user1", sPassword, "contoso.com");
serviceEST.AutodiscoverUrl("user1@contoso.com");

// Create the appointment and set properties on the appointment.
// DateTime properties will be scoped to the time zone of serviceEST (Eastern Standard Time).
Appointment appointment = new Appointment(serviceEST);
appointment.Subject = "Training Class";
appointment.Body = "The training class is from 10:00 A.M. to 11:00 A.M. Eastern Standard Time.";
appointment.Start = new DateTime(2009, 3, 1, 10, 0, 0);
appointment.End = appointment.Start.AddHours(1);
appointment.ReminderDueBy = new DateTime(2009, 3, 1, 9, 45, 0);
appointment.Location = "Training Room";

// The DateTime properties will be saved in Eastern Standard Time.
Console.WriteLine("Reminder Due By: " + appointment.ReminderDueBy);  // 9:45 A.M.
Console.WriteLine("Start: " + appointment.Start);  // 10:00 A.M.
Console.WriteLine("End: " + appointment.End);  // 11:00 A.M.

// Save the appointment.
appointment.Save(SendInvitationsMode.SendToNone);

//*************************************************
//* Get the appointment in local time (Pacific Standard Time).
//*************************************************

// Instantiate the ExchangeService object without specifying time zone. 
// The ExchangeService time zone will be set to the computer's local time zone (Pacific Standard Time).
ExchangeService serviceLocal = new ExchangeService();

// Set the credentials for the ExchangeService, by specifying the user name, password, and domain, and use Autodiscover to set the Url.
serviceLocal.Credentials = new WebCredentials("user1", sPassword, "contoso.com");
serviceLocal.AutodiscoverUrl("user1@contoso.com");

// Retrieve the appointment by using serviceLocal.
Appointment apptLocal = Appointment.Bind(serviceLocal, appointment.Id);

// Because the ExchangeService time zone is local time, DateTime properties are returned in local time (Pacific Standard Time). 
Console.WriteLine("Reminder Due By: " + apptLocal.ReminderDueBy);  // Reminder Due By: 3/1/2009 6:45 A.M.
Console.WriteLine("Start: " + apptLocal.Start);  // Start: 3/1/2009 7:00 A.M.
Console.WriteLine("End: " + apptLocal.End);  // End: 3/1/2009 8:00 A.M.
Console.WriteLine("End (Kind): " + apptLocal.End.Kind);  // End (Kind): Local

//*************************************************
//* Get the appointment in Eastern Standard Time.
//*************************************************

// Retrieve the appointment by using serviceEST.
Appointment apptEST = Appointment.Bind(serviceEST, appointment.Id);

// Because the ExchangeService time zone is Eastern Standard Time, DateTime properties are returned in Eastern Standard Time. 
Console.WriteLine("Reminder Due By: " + apptEST.ReminderDueBy);  // Reminder Due By: 3/1/2009 9:45 A.M.
Console.WriteLine("Start: " + apptEST.Start);  // Start: 3/1/2009 10:00 A.M.
Console.WriteLine("End: " + apptEST.End);  // End: 3/1/2009 11:00 A.M.
Console.WriteLine("End (Kind): " + apptEST.End.Kind);  // End (Kind): Unspecified

//*************************************************
//* Get the appointment in Central Standard Time.
//*************************************************

// Instantiate the ExchangeService object and specify the Central Standard Time time zone. 
ExchangeService serviceCST = new ExchangeService(TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time"));

// Set the credentials for the ExchangeService, by specifying the user name, password, and domain, and use Autodiscover to set the Url.
serviceCST.Credentials = new WebCredentials("user1", sPassword, "contoso.com");
serviceCST.AutodiscoverUrl("user1@contoso.com");

// Retrieve the appointment by using serviceCST.
Appointment apptCST = Appointment.Bind(serviceCST, appointment.Id);

// Because the ExchangeService time zone is Central Standard Time, DateTime properties are returned in Central Standard Time. 
Console.WriteLine("Reminder Due By: " + apptCST.ReminderDueBy);  // Reminder Due By: 3/1/2009 8:45 A.M.
Console.WriteLine("Start: " + apptCST.Start);  // Start: 3/1/2009 9:00 A.M.
Console.WriteLine("End: " + apptCST.End);  // End: 3/1/2009 10:00 A.M.
Console.WriteLine("End (Kind): " + apptCST.End.Kind);  // End (Kind): Unspecified

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.

See also

Concepts

Working with time zones by using the EWS Managed API 2.0

Time zones in the EWS Managed API 2.0