Expand an iCalendar recurrence rule into dated occurrences within a time window. events.ics is in the download; its contents are shown below.
dotnet add package RecursiveAI.OneMail.CalendarRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneMail.Calendar; using RecursiveAI.OneMail.Calendar.Ics; using RecursiveAI.OneMail.Calendar.Recurrence; var doc = ContentDocument.Parse( File.ReadAllBytes("events.ics")); var cal = IcsDocument.Calendars(doc).First(); var window = OccurrenceWindow.From( new DateTime(2026, 3, 1, 0, 0, 0, DateTimeKind.Utc), TimeSpan.FromDays(31)); foreach (var item in CalendarRecurrence.Expand(cal, window)) Console.WriteLine(item.StartUtc?.ToString( "yyyy-MM-dd HH:mm", System.Globalization.CultureInfo.InvariantCulture));
Unzip the example, then dotnet run.
The snippet at the top prints:
2026-03-02 14:00 2026-03-16 13:00 2026-03-23 13:00
The full program
The download’s Program.cs also prints resolved local and UTC times and expansion defects.
using RecursiveAI.OneMail.Calendar; using RecursiveAI.OneMail.Calendar.Ics; using RecursiveAI.OneMail.Calendar.Recurrence; var doc = ContentDocument.Parse(File.ReadAllBytes("events.ics")); var calendar = IcsDocument.Calendars(doc).First(); var window = OccurrenceWindow.From(new DateTime(2026, 3, 1, 0, 0, 0, DateTimeKind.Utc), TimeSpan.FromDays(31)); var report = new ExpansionReport(); foreach (var occurrence in CalendarRecurrence.Expand(calendar, window, report: report)) Console.WriteLine($"{occurrence.Start.Value:yyyy-MM-dd HH:mm} -> {occurrence.StartUtc:yyyy-MM-dd HH:mm} UTC"); Console.WriteLine($"Expansion defects: {report.Defects.Count}");
2026-03-02 09:00 -> 2026-03-02 14:00 UTC 2026-03-16 09:00 -> 2026-03-16 13:00 UTC 2026-03-23 09:00 -> 2026-03-23 13:00 UTC Expansion defects: 0
Expansion does not throw on content: it reports repairs, unknown zones and cut-offs in ExpansionReport.
The input, events.ics, is a synthetic example included in the zip. It uses CRLF line endings.
BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example//Calendar//EN BEGIN:VEVENT UID:meeting@example.org DTSTAMP:20260301T000000Z DTSTART;TZID=America/New_York:20260302T090000 DTEND;TZID=America/New_York:20260302T100000 RRULE:FREQ=WEEKLY;COUNT=4 EXDATE;TZID=America/New_York:20260309T090000 SUMMARY:Planning END:VEVENT END:VCALENDAR
Variations
Append this to the full program to select starts within the window and stop after two occurrences:
var options = new ExpansionOptions { WindowMode = WindowMode.StartingIn, MaxOccurrences = 2 }; var limited = new ExpansionReport(); var items = CalendarRecurrence.Expand( calendar, window, options, limited).ToList(); Console.WriteLine($"Selected: {items.Count}"); foreach (var defect in limited.Defects) Console.WriteLine(defect.Kind);
Additional output:
Selected: 2 OccurrenceLimit
Related recipes
- Convert ICS to jCal and xCal in C#
- Convert vCard to jCard and xCard in C#
- Parse email bounce delivery status in C#
The short answer
Parse the ICS bytes with ContentDocument.Parse, get the calendar with IcsDocument.Calendars, and enumerate CalendarRecurrence.Expand over an OccurrenceWindow. Pass an ExpansionReport when you need to know whether the enumeration repaired an input or stopped at a resource limit. The full program above does this without a calendar account or network request.
Expansion is different from reading a rule. An RRULE describes a series; an occurrence has a particular start and end. Expanding a whole VCALENDAR also gives the engine access to its time zones and replacement events. Passing an isolated RRULE string would leave out those parts of the schedule.
How do you expand an iCalendar recurrence in C#?
Choose a window before you enumerate. OneMail uses a half-open UTC window: the start is included and the end is excluded. By default it selects events that overlap the window, not just events that begin inside it. This matters for an overnight appointment already running when your calendar view opens. Use WindowMode.StartingIn, as in the variation, when the start time alone should decide inclusion.
The sample has a weekly rule with a count of four. Its EXDATE removes the second occurrence, leaving the three printed dates. The count applies before exclusions; it does not promise four returned rows. OneMail also honors RDATE and EXRULE. A component with a matching UID and RECURRENCE-ID replaces the occurrence it names; a THISANDFUTURE override shifts later occurrences too. These rules are documented in recurrence expansion.
Enumeration is lazy. Read the report after finishing the enumeration, because defects accumulate while instances are generated. The variation deliberately caps the result at two and receives OccurrenceLimit; those two rows must not be mistaken for the complete month’s schedule.
How do RRULE time zones work?
Keep the original wall-clock value and the UTC instant separate. The sample appointment remains at nine in New York while its UTC time changes after daylight saving begins. Start carries the event’s date/time representation; StartUtc is the resolved instant. Floating times, date-only events and unresolved zones have no UTC instant, so StartUtc is null. Do not substitute a server-local time zone for those values without an application decision.
OneMail first looks for a matching VTIMEZONE in the calendar. It can then use UTC names, the runtime’s IANA database and its documented name mappings. The sample relies on the runtime knowing America/New_York. A file with its own VTIMEZONE can supply its own observances instead.
For a local time in the skipped spring-forward hour, the default is to interpret it using the offset before the gap. SkippedTimePolicy.Skip instead omits it without counting it toward COUNT. For the repeated fall-back hour, the first instant is selected. Both cases produce typed ambiguity defects. An unknown zone also appears in the report; a missing instant is not a successful UTC conversion.
What is the iCalendar RRULE format?
An RRULE is a semicolon-separated recurrence value, such as FREQ=WEEKLY;COUNT=4, defined by RFC 5545 section 3.3.10. DTSTART supplies the starting value. A rule is not a list of dates, and an ICS file can contain exclusions, additions and overrides outside the rule itself.
OneMail does not expand non-Gregorian RSCALE values. An invalid rule is ignored with InvalidRule; inspect the report rather than assuming that a returned DTSTART proves the rest of a series was understood. Expansion reads the component tree without modifying it, so listing occurrences is not a conversion into a new calendar containing separate VEVENTs.