使用 Exchange 中的 EWS 创建全天事件Create all-day events by using EWS in Exchange

了解如何使用 EWS 托管 API 或 Exchange 中的 EWS 创建全天事件。Learn how to create all-day events by using the EWS Managed API or EWS in Exchange.

全天事件提供了一种表示整天或几天内发生的事情(例如,假日或假期)的方法。All-day events provide a way to represent something that happens for an entire day or multiple days—for example, a holiday, or vacation days. 使用 EWS 托管 API 或 EWS 创建全天事件是一个快照。Creating all-day events with the EWS Managed API or EWS is a snap. 这就像创建约会,但有一些小的变化。It's just like creating appointments, but with a few small changes.

设置开始时间和结束时间Setting start and end times

根据定义,全天事件将在特定日期的午夜开始,并在稍后结束24小时(或24小时的多个小时)。By definition, all-day events start at midnight on a specific day, and end 24 hours (or a multiple of 24 hours) later. 但是,EWS 托管 API 和 EWS 允许您在创建全天事件时指定午夜以外的时间。However, the EWS Managed API and EWS allow you to specify times other than midnight when creating all day events. 如果你不知道这些时间在服务器上的翻译方式,这可能会导致意外行为。This can lead to unintended behavior if you're not aware of how these times get translated on the server.

收到请求以创建新的全天事件(在请求或约会的时区中)开始和/或结束时间时,这些时间将根据以下规则调整为相应时区中的午夜:When a request is received to create a new all-day event with non-midnight (in the time zone of the request or appointment) start and/or end times, those times get adjusted to midnight in the appropriate time zone according to the following rules:

  • 非午夜开始时间将调整为指定的时间之前的午夜。Non-midnight start times are adjusted to the midnight prior to the time specified. 例如,1:00 年6月6日下午6点调整为 12:00 AM。For example, 1:00 PM on June 6 gets adjusted to 12:00 AM on June 6.

  • 在指定的时间之后,非午夜结束时间将调整为午夜。Non-midnight end times are adjusted to the midnight after the time specified. 例如,1:00 年6月6日在6月7日调整为 12:00 AM。For example, 1:00 PM on June 6 gets adjusted to 12:00 AM on June 7.

因此,您创建的全天事件始终包含您指定的开始时间和结束时间,但可能会因班次转到午夜而在用户日历上声明额外的时间。So the all-day event that you create is always inclusive of the start and end time that you specify, but might claim additional time on the user's calendar due to the shift to midnight. 由于服务器会将开始时间和结束时间调整为午夜,因此建议您在午夜指定开始时间和结束时间以避免对时间的任何意外更改。Because the server will adjust the start and end time to midnight, we recommend that you specify your start and end time at midnight to avoid any unintended changes to the times.

创建全天事件时,考虑时区也是非常重要的。It's also important to consider time zones when creating all-day events. 由于 Exchange server 在请求或约会的时区中强制执行午夜的开始和结束时间,因此在为不同时区配置的客户端中查看该全天事件可能会产生意外的结果。Because the Exchange server enforces a midnight start and end time in the time zone of the request or appointment, viewing that all-day event in a client configured for a different time zone can yield unexpected results. 根据客户端的不同,它可能会显示为包含您不打算包含的额外天数的全天事件,也可能不会完全显示为全天事件。Depending on the client, it might appear as an all-day event with extra days that you did not intend to include, or it might not appear as an all-day event altogether. 因此,我们建议您在创建全天事件时尽可能使用用户的首选时区。Because of this, we recommend that you use the user's preferred time zone whenever possible when you create all-day events.

使用 EWS 托管 API 创建全天事件Create an all-day event by using the EWS Managed API

下面的示例演示如何使用 EWS 托管 API 创建一个全天事件,_从起始日期参数指定_的日期开始,并持续_numDays_参数指定的天数。The following example shows how to use the EWS Managed API to create an all-day event, starting on the date specified by the startDate parameter and lasting for the number of days specified by the numDays parameter. 请注意,将在ExchangeService属性指定的时区中创建约会。Note that the appointment will be created in the time zone specified by the ExchangeService.TimeZone property. 此示例假定已使用凭据Url属性的有效值对在_Service_参数中传递的ExchangeService对象进行了初始化。This example assumes that the ExchangeService object passed in the service parameter has been initialized with valid values for the Credentials and Url properties.

static void CreateAllDayAppointment(ExchangeService service, DateTime startDate, int numDays)
{
    // Best practice is to set the start date to midnight
    // on the first day of the all-day event.
    DateTime startDateMidnight = startDate.Date;
    // The end date should be midnight on the first day
    // after the event.
    DateTime endDateMidnight = startDateMidnight.AddDays(numDays);
    Appointment allDayEvent = new Appointment(service);
    // Set IsAllDayEvent to true.
    allDayEvent.IsAllDayEvent = true;
    // Set other properties.
    allDayEvent.Subject = "Vacation";
    allDayEvent.LegacyFreeBusyStatus = LegacyFreeBusyStatus.OOF;
    allDayEvent.Start = startDateMidnight;
    allDayEvent.End = endDateMidnight;
    // Save the appointment.
    try
    {
        allDayEvent.Save(WellKnownFolderName.Calendar, SendInvitationsMode.SendToNone);
        Console.WriteLine("All day event created.");
    }
    catch (Exception ex)
    {
        Console.WriteLine("Error saving all day event: {0}", ex.Message);
    }
}

使用 EWS 创建全天事件Create an all-day event by using EWS

以下示例显示了用于创建全天事件的 EWS CreateItem 操作请求。The following example shows an EWS CreateItem operation request to create an all-day event. 约会在东部时区中创建,如TimeZoneContext元素所示。The appointment is created in the Eastern time zone, as indicated by the TimeZoneContext element. 请注意, StartEnd元素的值的时间部分均为04:00Z,这将在夏令时转换为东部时区中的午夜。Notice that the time portion of the values of the Start and End elements are both 04:00Z, which converts to midnight in the Eastern time zone during daylight saving time.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
    <t:TimeZoneContext>
      <t:TimeZoneDefinition Id="Eastern Standard Time" />
    </t:TimeZoneContext>
  </soap:Header>
  <soap:Body>
    <m:CreateItem SendMeetingInvitations="SendToNone">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="calendar" />
      </m:SavedItemFolderId>
      <m:Items>
        <t:CalendarItem>
          <t:Subject>Vacation</t:Subject>
          <t:Start>2014-06-09T04:00:00.000Z</t:Start>
          <t:End>2014-06-10T04:00:00.000Z</t:End>
          <t:IsAllDayEvent>true</t:IsAllDayEvent>
          <t:LegacyFreeBusyStatus>OOF</t:LegacyFreeBusyStatus>
        </t:CalendarItem>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

另请参阅See also