Create all-day events by using EWS in Exchange
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. 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
By definition, all-day events start at midnight on a specific day, and end 24 hours (or a multiple of 24 hours) later. 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. 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. 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. 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.
Create an all-day event by using the EWS Managed API
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. Note that the appointment will be created in the time zone specified by the ExchangeService.TimeZone property. 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);
}
}
Create an all-day event by using EWS
The following example shows an EWS CreateItem operation request to create an all-day event. The appointment is created in the Eastern time zone, as indicated by the TimeZoneContext element. 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="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://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>