Skip to content

Migrating Guides

Jump to bottom
axunonb edited this page Jul 20, 2025 · 7 revisions

📦 iCal.NET v5.x Migration Guide

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.

What's New in iCal.NET v5.x

🚀 Improved Performance and Stability

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:

v4.3.1

Method Mean Error StdDev Gen0 Gen1 Allocated
SerializeCalendar 6.574 us 0.0761 us 0.0712 us 1.3733 0.0305 21.24 KB
DeserializeCalendar 16.047 us 0.2156 us 0.2016 us 3.7231 0.2441 57.03 KB
Get1000Occurrences 4,011.561 us 56.7021 us 53.0392 us 679.6875 515.6250 10426.99 KB

v5.0.0

Method Mean Error StdDev Gen0 Gen1 Allocated
SerializeCalendar 6.416 us 0.0614 us 0.0544 us 1.5640 0.0381 20.03 KB
DeserializeCalendar 14.119 us 0.1875 us 0.1754 us 3.1281 0.1526 47.95 KB
Get1000Occurrences 844.840 us 6.9896 us 6.1961 us 144.5313 102.5391 2218.26 KB

🐞 Issues from v4.x Addressed

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.

🔮 Future

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.

Migration

❓ Nullable Reference Types (NRT) Support

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.

🔧 Major Breaking Changes

1. Removal of IDateTime and PeriodList

  • 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(toDate);

2. Evaluation API Overhaul

  • Removed: ClearEvaluation, RecurrenceEvaluationModeType, RecurrenceRestrictionType
  • New: EvaluationOptions, Evaluator pattern

Update your recurrence evaluation logic to use EvaluationOptions and CalDateTime.

3. Service Provider Interfaces Removed

  • All IServiceProvider implementations and related methods (GetService, SetService, etc.) were removed from nearly all types.

4. Occurrence and FreeBusy Methods Changed

  • Old methods using IDateTime and System.DateTime were removed.
  • New methods use CalDateTime and EvaluationOptions.

Example:

calendar.GetOccurrences(CalDateTime start, EvaluationOptions options);
calendar.GetOccurrences(start).TakeWhileBefore(end);

Note: Use TakeWhileBefore to limit occurrences to a specific end date.

Note: From occurrences use Period.StartTime and Period.Duration or Period.EffectiveDuration to work with durations instead of TimeSpan or end date.

🆕 New Features and Enhancements

✅ CalDateTime Enhancements

  • Now a standalone type (no longer implements IDateTime)
  • New constructors and properties like IsFloating, UtcNow, TimeOnly? Time

✅ Duration Struct

  • Replaces TimeSpan in many places
  • Supports calendar-aware durations

✅ EvaluationOptions

  • Controls evaluation behavior (e.g., MaxUnmatchedIncrementsLimit)

🗑️ Removed Types

  • IDateTime, PeriodList, RecurrenceEvaluationModeType, RecurrenceRestrictionType
  • IServiceProvider from all calendar-related types

🧪 Updated Method Signatures

Old Signature New Signature
GetOccurrences(IDateTime, IDateTime) GetOccurrences(CalDateTime, EvaluationOptions)
GetFreeBusy(IDateTime, IDateTime) GetFreeBusy(CalDateTime, CalDateTime)
PollAlarms(IDateTime, IDateTime) PollAlarms(CalDateTime, CalDateTime)

🧼 Equality and HashCode Methods Removed

  • Many Equals, GetHashCode, and CompareTo methods were removed or replaced.
  • Use new comparison methods on CalDateTime or implement custom logic.

🧭 Time Zone Handling

  • Introduced TimeZoneResolvers and DefaultTimeZoneResolver
  • Use these for resolving time zones by ID

🧩 Serialization Changes

  • All serializers now implement System.IServiceProvider instead of Ical.Net.IServiceProvider
  • Some serializers have new validation methods (e.g., CheckRange, CheckMutuallyExclusive)

✅ Migration Checklist

  • Replace all IDateTime with CalDateTime
  • Replace PeriodList with ExceptionDates or RecurrenceDates
  • Update all GetOccurrences, GetFreeBusy, and PollAlarms calls
  • Remove usage of IServiceProvider and related service methods
  • Use EvaluationOptions for recurrence evaluation
  • Replace TimeSpan with Duration where applicable
  • Update equality and comparison logic as needed
  • Test thoroughly, as many subtle behaviors (especially around recurrence and time zones) may have changed.

Migrating to v4 (outdated)

iCal.NET v4+ targets .NET Standard 1.3, and migrating to the latest version(s) shouldn't take long if you're targeting .NET Core 1.3+ or .NET Framework 4.6+.

  • Event is now CalendarEvent
  • At this point, most of the pointless interfaces (IEvent, ICalendarCollection, etc.) are gone. Use the concrete types instead, which is usually a matter of removing the I prefix. IRecurrencePattern is now RecurrencePattern, for example.
  • Lots of namespace reorganization. You'll want to use IntelliSense to import the new namespaces. In many cases, the type names haven't changed, but their location has.
  • The ical.net.Collections assembly is completely gone.
  • The ANTLR-based parser is gone in favor of chescock's SimpleDeserializer which is about twice as fast, and is quite a lot simpler to read and understand.
  • CalendarCollection.Load() loads a CalendarCollection.
  • Calendar.Load loads a Calendar.
  • CalendarComponent.Load<T>() loads whatever type you're looking for.
  • See the release notes for additional v4 details.

Clone this wiki locally