This guide outlines the breaking changes, removals, and new patterns introduced in iCal.NET v5.x, helping you update your codebase from v4.3.1.

In general, users' feedback has been overwhelmingly positive, and the migration is expected to be straightforward for most users implementing standard iCalendar functionality.

For a detailed list of changes, please refer to the API Changes v4 to v5.

The v5.x release includes significant performance improvements and stability enhancements, particularly in recurrence evaluation and timezone handling. Below are benchmark comparisons between v4.3.1 and v5.0.0 GA:

Around 50 issues have been addressed in the v5.0.0 release. These include many timezone handling improvements and recurrence evaluation fixes.

In case you have implemented workarounds for any of these issues, please review the GitHub issue tracker for details on how they have been resolved.

We encourage all users to migrate to iCal.NET v5.x to benefit from improved performance, stability, and null-safety.

The project is actively maintained, and we are working on further improvements that may introduce additional breaking changes in future major releases.

Your feedback is valuable — please let us know about your migration experience or any issues by opening an issue or discussion on the GitHub repository.

iCal.NET v5.x now enables Nullable Reference Types (NRT) throughout the library. This means:

• Reference type nullability is now explicitly annotated in all public APIs.
• The compiler will provide warnings for possible null reference issues, helping you write safer and more robust code.
• Consumers targeting .NET Core 3.0+, .NET Standard 2.1+, or .NET 5+ will benefit from improved static analysis and null-safety.

Review your code for new nullable warnings after upgrading, and update your null-handling logic as needed.

• Replaced by: CalDateTime, ExceptionDates, and RecurrenceDates
• Impact: All APIs using IDateTime or PeriodList must be updated to use the new types.

Before:

IDateTime start = ...;
calendar.GetOccurrences(start, end);

After:

CalDateTime start = ...;
CalDateTime toDate = ...;
calendar.GetOccurrences(start, new EvaluationOptions());
calendar.GetOccurrences(start).TakeWhileBefore