Overview of a recurring series in the EWS Managed API 2.0
Learn about recurring series and recurrence patterns in the EWS Managed API.
Last modified: January 25, 2013
Applies to: EWS Managed API | Exchange Server 2007 Service Pack 1 (SP1) | 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.
In this article
Items in a recurring series
Recurrence patterns
Recurrence ranges
A recurring series is a sequence of calendar items that follow a recurrence pattern and have a recurrence range. This topic provides an overview of a recurring series in the EWS Managed API, including the items in a recurring series and the concepts of recurrence pattern and recurrence range.
Items in a recurring series
A recurring series consists of a recurring master item, occurrence items, and sometimes exception items. The following table defines these item types.
Item type |
Description |
|---|---|
Recurring master item |
The item that anchors the recurring series and holds all recurrence pattern and recurrence range information. Each recurring series has one recurring master item. |
Occurrence items |
The sequence of calendar items in a recurring series that adhere to the recurrence pattern of the series. |
Exception items |
Items in the series that started as occurrence items, but were modified so that they no longer have the same property values as occurrence items. Modifying any property on an occurrence item makes it an exception item. |
Recurrence information
All recurrence information is stored on the recurring master item. Although recurrence properties exist on all calendar items, they are populated only on recurring master items. Recurrence properties are null on any calendar item that is not a recurring master item. The following table lists the recurrence properties that are populated on the recurring master item.
Property name |
Description |
|---|---|
Recurrence |
A property that contains the recurrence pattern and recurrence range of the series. |
FirstOccurrence |
An OccurrenceInfo object that has the same ItemID, Start, and End property values as the first calendar item (occurrence or exception) in the series. |
LastOccurrence |
An OccurrenceInfo object that has the same ItemID, Start, and End property values as the last calendar item (occurrence or exception) in the series. |
ModifiedOccurrences |
A collection of OccurrenceInfo objects that are representative of the exception items in the series. The objects have the same ItemID, Start, End, and OriginalStart property values as the exception items in the series. The ModifiedOccurrences array does not contain information about the properties that were modified to create the exceptions; it just provides these four property values for each exception item. |
DeletedOccurrences |
A collection of OccurrenceInfo objects that are representative of the items that have been deleted from the series. The objects have the same Start property values as the items that were deleted from the series. |
Indexing of occurrence items and exception items
When a recurring series is created, each occurrence item has as index that represents its position in the series. The index starts at one and advances by one for each item in the series. When an occurrence item is modified and becomes an exception item, it maintains its index in the series. Also, when an occurrence item or exception item is deleted, the indexes of remaining occurrence items and exception items remain the same. For information about how to access occurrence items and exception items in a recurring series, see Accessing calendar items in a recurring series by using the EWS Managed API 2.0.
Recurrence patterns
The recurrence pattern defines the frequency of occurrences of items in the recurring series. The following table lists the recurrence patterns that you can use to create a recurring series by setting the Recurrence property on the Appointment object in the Microsoft Exchange Web Services (EWS) Managed API.
Recurrence pattern |
Example |
|---|---|
Recurrence.DailyPattern |
Use to create a series of calendar items that recur daily. Or, use to create a series of calendar items that recur every third day. |
Recurrence.WeeklyPattern |
Use to create a series of calendar items that recur every Monday. Or, use to create a series of calendar items that recur on Monday, Wednesday, and Friday each week. Or, use to create a series of calendar items that recur on Monday and Tuesday every second week. |
Recurrence.MonthlyPattern |
Use to create a series of calendar items that recur on the 15th of each month. Or, use to create a series of calendar items that recur on the 15th of every third month. |
Recurrence.RelativeMonthlyPattern |
Use to create a series of calendar items that recur on the third Monday of each month. Or, use to create a series of calendar items that recur on the third Monday of every fourth month. |
Recurrence.YearlyPattern |
Use to create a series of calendar items that recur annually on November 15. |
Recurrence.RelativeYearlyPattern |
Use to create a series of calendar items that recur annually on the last Monday in November. |
Recurrence ranges
The recurrence range defines the start and end date of the recurring series. The following table lists the items on the Appointment.Recurrence object that you can use to set the recurrence range by using the EWS Managed API.
Item |
Description |
|---|---|
StartDate property |
Use this property to set the date and time that the recurring series starts. |
EndDate property |
Use this property to set the date after which the recurring series ends. Setting EndDate resets the value of NumberOfRecurrences. |
NumberOfRecurrences property |
Use this property to set the number of occurrences after which the series ends. |
NeverEnds method |
Call this method to indicate that the occurrences recur indefinitely. Calling this method is the equivalent of setting EndDate and NumberOfRecurrences to null. |
See also