Crear citas en una zona horaria específica mediante EWS en Exchange
Cuando se crea una cita o reunión en un calendario de Exchange, la zona horaria que se usa para especificar las horas de inicio y finalización se guarda como zona horaria de creación para la cita. Esa zona horaria también se usa para interpretar los valores de fecha y hora que no tienen una zona horaria explícita especificada, por lo que es importante comprender las opciones para especificar la zona horaria.
Creación de citas en distintas zonas horarias mediante la API administrada de EWS
Al crear citas o reuniones mediante la API administrada de EWS, tiene tres opciones para especificar la zona horaria:
Para usar la zona horaria del equipo donde se ejecuta la API administrada de EWS, no especifique una zona horaria al crear el objeto ExchangeService .
Para usar una zona horaria específica para todas las propiedades de fecha y hora, incluidas las propiedades al crear una nueva cita o reunión, especifique una zona horaria en el constructor para el objeto ExchangeService .
Para usar una zona horaria diferente a la especificada en la propiedad ExchangeService.TimeZone , use las propiedades Appointment.StartTimeZone y Appointment.EndTimeZone .
Nota:
La propiedad EndTimeZone solo está disponible cuando la propiedad ExchangeService.RequestedServerVersion se establece en Exchange2010 o posterior. Si no está disponible, la configuración de StartTimeZone se aplica a las horas de inicio y finalización de la cita.
En el ejemplo siguiente, la API administrada de EWS se usa para crear tres citas. Cada cita se establece para que comience a la 1:00 p.m. dos días a partir de ahora, en una zona horaria no especificada, y finalice una hora más tarde. La primera cita se crea en la zona horaria del equipo cliente mediante el comportamiento predeterminado de la API administrada de EWS. El segundo se crea en la zona horaria central mediante las propiedades Appointment.StartTimeZone y Appointment.EndTimeZone , en este caso también establecemos la propiedad extendida TimeZoneDescription en el mismo valor que TimeZone que se usa. El tercero se crea en la zona horaria de mountain mediante la propiedad ExchangeService.TimeZone .
using Microsoft.Exchange.WebServices.Data;
using System.Security;
static void CreateAppointments(string userEmail, SecureString userPass)
{
// *****************************************************
// Create an appointment using the client computer's time zone.
// *****************************************************
// Do not specify a time zone when creating the ExchangeService.
ExchangeService clientTZService = new ExchangeService(ExchangeVersion.Exchange2010);
clientTZService.Credentials = new NetworkCredential(userEmail, userPass);
clientTZService.AutodiscoverUrl(userEmail, redirectionCallback);
// Create the appointment.
Appointment clientTZAppt = new Appointment(clientTZService);
clientTZAppt.Subject = "Appointment created using client time zone";
clientTZAppt.Body = new MessageBody(string.Format("Time zone: {0}", clientTZService.TimeZone.DisplayName));
// Set the start time to 1:00 PM two days from today.
DateTime startTime = new DateTime(DateTime.Now.Year, DateTime.Now.Month, DateTime.Now.Day + 2);
startTime = startTime.AddHours(13);
clientTZAppt.Start = startTime;
// Set the end time to 2:00 PM on that same day.
DateTime endTime = startTime.AddHours(1);
clientTZAppt.End = endTime;
// Save the appointment to the default calendar.
try
{
// This method results in a call to EWS.
clientTZAppt.Save(SendInvitationsMode.SendToNone);
}
catch (Exception ex)
{
Console.WriteLine("Error saving appointment: {0}", ex.Message);
}
// *****************************************************
// Create an appointment in the Central time zone by
// using the StartTimeZone property.
// *****************************************************
// Extended Property for the TimeZone Description
ExtendedPropertyDefinition tzDescription = new ExtendedPropertyDefinition(DefaultExtendedPropertySet.Appointment, 33332, MapiPropertyType.String);
// Retrieve the Central time zone.
TimeZoneInfo centralTZ = TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time");
// Create the appointment.
Appointment centralTZAppt = new Appointment(clientTZService);
centralTZAppt.Subject = "Appointment created using Central time zone";
centralTZAppt.Body = new MessageBody(string.Format("Time zone: {0}", centralTZ.DisplayName));
// Set the time zone on the appointment.
centralTZAppt.StartTimeZone = centralTZ;
centralTZAppt.EndTimeZone = centralTZ;
// Set the start time to 1:00 PM two days from today.
centralTZAppt.Start = startTime;
// Set the end time to 2:00 PM on that same day.
centralTZAppt.End = endTime;
// Set the TimeZone Description on the appointment/meeting
centralTZAppt.SetExtendedProperty(tzDescription, centralTZ.DisplayName);
// Save the appointment to the default calendar.
try
{
// This method results in a call to EWS.
centralTZAppt.Save(SendInvitationsMode.SendToNone);
}
catch (Exception ex)
{
Console.WriteLine("Error saving appointment: {0}", ex.Message);
}
// *****************************************************
// Create an appointment in the Mountain time zone by
// using the ExchangeService.TimeZone property.
// *****************************************************
// Specify the Mountain time zone when creating the ExchangeService.
TimeZoneInfo mountainTZ = TimeZoneInfo.FindSystemTimeZoneById("Mountain Standard Time");
ExchangeService mountainTZService = new ExchangeService(ExchangeVersion.Exchange2010, mountainTZ);
mountainTZService.Credentials = new NetworkCredential(userEmail, userPass);
mountainTZService.AutodiscoverUrl(userEmail, redirectionCallback);
// Create the appointment.
Appointment mountainTZAppt = new Appointment(mountainTZService);
mountainTZAppt.Subject = "Appointment created using Mountain time zone";
mountainTZAppt.Body = new MessageBody(string.Format("Time zone: {0}", mountainTZService.TimeZone.DisplayName));
// Set the start time to 1:00 PM two days from today.
mountainTZAppt.Start = startTime;
// Set the end time to 2:00 PM on that same day.
mountainTZAppt.End = endTime;
// Save the appointment to the default calendar.
try
{
// This method results in a call to EWS.
mountainTZAppt.Save(SendInvitationsMode.SendToNone);
}
catch (Exception ex)
{
Console.WriteLine("Error saving appointment: {0}", ex.Message);
}
}
Nota:
En el segundo ejemplo, la propiedad extendida TimeZoneDescription debe establecerse para evitar un problema de potenciación cuando se envían actualizaciones de reunión al destinatario enternal.
Cuando este ejemplo se ejecuta en un equipo cliente configurado en la zona horaria oriental y las tres citas que crea se ven desde un cliente configurado en la zona horaria oriental, aparecen a las 13:00, a las 23:00 y a las 15:00, respectivamente.
Creación de citas en distintas zonas horarias mediante EWS
Al crear citas o reuniones mediante EWS, tiene tres opciones para especificar la zona horaria:
Para usar la hora universal coordinada (UTC), no incluya un elemento TimeZoneContext , un elemento MeetingTimeZone (solo Exchange 2007) ni elementos StartTimeZone y EndTimeZone (Exchange 2010 y versiones posteriores) en la solicitud de operación CreateItem .
Para usar una zona horaria específica para todas las propiedades de fecha y hora, incluidas las propiedades al crear una nueva cita o reunión, especifique una zona horaria en el elemento TimeZoneContext en la solicitud de operación CreateItem .
Para usar una zona horaria diferente a la especificada en el elemento TimeZoneContext , incluya un elemento TimeZoneContext , un elemento MeetingTimeZone (solo Exchange 2007) o elementos StartTimeZone y EndTimeZone (Exchange 2010 y versiones posteriores) en la solicitud de operación CreateItem .
En el ejemplo siguiente, la solicitud de operación CreateItem crea una cita mediante UTC. Observe que el elemento TimeZoneContext , el elemento StartTimeZone y el elemento EndTimeZone están ausentes. Los valores de los elementos Start y End se expresan en UTC.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010" />
</soap:Header>
<soap:Body>
<m:CreateItem SendMeetingInvitations="SendToNone">
<m:Items>
<t:CalendarItem>
<t:Subject>Appointment created using UTC</t:Subject>
<t:Body BodyType="HTML">Time zone: UTC</t:Body>
<t:Start>2023-02-07T17:00:00.000Z</t:Start>
<t:End>2023-02-07T18:00:00.000Z</t:End>
</t:CalendarItem>
</m:Items>
</m:CreateItem>
</soap:Body>
</soap:Envelope>
En el ejemplo siguiente, la solicitud de operación CreateItem usa los elementos StartTimeZone y EndTimeZone para especificar la zona horaria central para la cita. Observe que el elemento TimeZoneContext está ausente. Sin embargo, si estuviera presente, los valores de los elementos StartTimeZone y EndTimeZone invalidarían su valor. De nuevo, los valores de los elementos Start y End se expresan en UTC. También establecemos la propiedad extendida TimeZoneDescription en el mismo valor que TimeZone que se usa.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010" />
</soap:Header>
<soap:Body>
<m:CreateItem SendMeetingInvitations="SendToNone">
<m:Items>
<t:CalendarItem>
<t:Subject>Appointment created using Central time zone</t:Subject>
<t:Body BodyType="HTML">Time zone: (UTC-06:00) Central Time (US &amp; Canada)</t:Body>
<t:ExtendedProperty>
<t:ExtendedFieldURI DistinguishedPropertySetId="Appointment" PropertyId="33332" PropertyType="String" />
<t:Value>(UTC-06:00) Central Time (US & Canada)</t:Value>
</t:ExtendedProperty>
<t:Start>2023-02-07T18:00:00.000</t:Start>
<t:End>2023-02-07T19:00:00.000</t:End>
<t:StartTimeZone Id="Central Standard Time" />
<t:EndTimeZone Id="Central Standard Time" />
</t:CalendarItem>
</m:Items>
</m:CreateItem>
</soap:Body>
</soap:Envelope>
En el ejemplo siguiente, la solicitud de operación CreateItem establece el elemento TimeZoneContext en la zona horaria de mountain. Observe que los elementos StartTimeZone y EndTimeZone están ausentes. Again, the Start and End element values are expressed in UTC.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Mountain Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:CreateItem SendMeetingInvitations="SendToNone">
<m:Items>
<t:CalendarItem>
<t:Subject>Appointment created using Mountain time zone</t:Subject>
<t:Body BodyType="HTML">Time zone: (UTC-07:00) Mountain Time (US &amp; Canada)</t:Body>
<t:Start>2023-02-07T19:00:00.000</t:Start>
<t:End>2023-02-07T20:00:00.000</t:End>
</t:CalendarItem>
</m:Items>
</m:CreateItem>
</soap:Body>
</soap:Envelope>
Cuando las tres citas creadas por las solicitudes de ejemplo de EWS anteriores se ven desde un cliente configurado en la zona horaria oriental, aparecen a las 13:00, a las 23:00 y a las 15:00, respectivamente.
Ahora que sabe cómo crear citas en zonas horarias específicas, puede actualizar las zonas horarias de las citas existentes a otra.