---
title: "Expand recurring iCalendar events in C#"
url: https://recursiveai.org/onemail/cookbook/expand-recurring-calendar-events/
description: "Expand iCalendar RRULE events in C# with a bounded window, exclusions and time-zone resolution. Inspect occurrence times and expansion defects."
version: "1.0.1"
---

# Expand recurring iCalendar events in C#

**OneMail** is a free, open-source email library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneMail.Calendar) · [GitHub](https://github.com/recursive-ai-oss/onemail-csharp) · [Docs](https://recursiveai.org/onemail/docs/) · [Download example (.zip)](https://recursiveai.org/onemail/cookbook/expand-recurring-calendar-events/expand-recurring-calendar-events.zip)

Expand an iCalendar recurrence rule into dated occurrences within a time window. `events.ics` is in the download; its contents are shown below.

```shell
dotnet add package RecursiveAI.OneMail.Calendar
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/onemail/cookbook/expand-recurring-calendar-events/expand-recurring-calendar-events.zip), then `dotnet run`.

The snippet at the top prints:

```text
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.

```csharp
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}");
```

```text
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.

```text
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:

```csharp
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:

```text
Selected: 2
OccurrenceLimit
```

## Related recipes

- [Convert ICS to jCal and xCal in C#](https://recursiveai.org/onemail/cookbook/convert-ics-to-jcal-and-xcal/)
- [Convert vCard to jCard and xCard in C#](https://recursiveai.org/onemail/cookbook/convert-vcard-to-jcard-and-xcard/)
- [Parse email bounce delivery status in C#](https://recursiveai.org/onemail/cookbook/parse-delivery-status-notification/)

## 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](https://recursiveai.org/onemail/docs/recurrence/).

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](https://www.rfc-editor.org/rfc/rfc5545.html#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.
