How to associate a timezone to an all-day event

[RemcoBlok]

Good work on the progress on V5! I found a regression in the 5.0.0-daily.3 pre-release though. In V4 I could specify a timezone for all-day events (where the start and end have no time component) and ical.net would serialize the timezone for all-day events.

BEGIN:VCALENDAR
PRODID:-//github.com/ical-org/ical.net//NONSGML ical.net 4.0//EN
VERSION:2.0
BEGIN:VEVENT
DTEND;TZID=Pacific Standard Time;VALUE=DATE:20241104
DTSTAMP:20250207T121642Z
DTSTART;TZID=Pacific Standard Time;VALUE=DATE:20241103
SEQUENCE:0
UID:e51ce49f-ba0f-41e4-b3a8-8fee04180c33
END:VEVENT
END:VCALENDAR

using the following code

Calendar calendar = new Calendar();

string timeZoneId = "Pacific Standard Time";

CalendarEvent myEvent = new CalendarEvent();
myEvent.Start = new CalDateTime(2024, 11, 3, timeZoneId);
myEvent.Start.HasTime = false;
myEvent.End = new CalDateTime(2024, 11, 4, timeZoneId);
myEvent.End.HasTime = false;

Debug.Assert(myEvent.IsAllDay);

calendar.Events.Add(myEvent);

CalendarSerializer serializer = new CalendarSerializer();
string schedulerData = serializer.SerializeToString(calendar);

In V5 ical.net no longer serializes the timezone for all-day events

BEGIN:VCALENDAR
PRODID:-//github.com/ical-org/ical.net//NONSGML ical.net 4.0//EN
VERSION:2.0
BEGIN:VEVENT
DTEND;VALUE=DATE:20241104
DTSTAMP:20250207T122102Z
DTSTART;VALUE=DATE:20241103
SEQUENCE:0
UID:a3eadb5a-5d4e-47ef-a13d-d5d66c94911e
END:VEVENT
END:VCALENDAR

using the following code

Calendar calendar = new Calendar();

string timeZoneId = "Pacific Standard Time";

DateTime start = new DateTime(2024, 11, 3);
DateTime end = new DateTime(2024, 11, 4);

CalendarEvent myEvent = new CalendarEvent();
myEvent.Start = new CalDateTime(start, timeZoneId, hasTime: false);
myEvent.End = new CalDateTime(end, timeZoneId, hasTime: false);

Debug.Assert(myEvent.IsAllDay);

calendar.Events.Add(myEvent);

CalendarSerializer serializer = new CalendarSerializer();
string schedulerData = serializer.SerializeToString(calendar);

It is important for me to specify a timezone for all-day events. When I have an all-day event specified in the PST timezone and view this event in a calendar user-interface component in the GMT timezone then it should not show it as an all-day event in the GMT timezone. Perhaps if I have an all-day event without specifying a timezone, it might show as an all-day event in any timezone (or only the system local timezone), but when I explicitly specify a timezone for the all-day event then it is an all-day event in that timezone only, because the start of the day in PST is not at the same (UTC) time as the start of the day in GMT (even daylight saving transitions in PST and GMT are not on the same day). Especially when I look for overlapping occurrences of events in different timezones, I need to know the timezone for all-day events the same as for non-all-day events.

Note that in V5 the constructors of CalDateTime do not make it easy to specify a timezone for an all-day event. It would be good if the overloads that take a DateOnly or (year, month, day) would also accept an optional timezone.

I also wonder if I should create the CalendarEvent with a Duration instead of an End date, but I believe it should work with an End date as well as long as I set hasTime to false and the effective duration is one day (or more). Please confirm.

It would also be good if CalendarEvent could have read-only properties for EffectiveEnd and EffectiveDuration like the CalPeriod of an Occurrence. CalendarEvent, CalPeriod and Duration could also benefit from a read-only ExactDuration property that returns a TimeSpan.

Thanks

-Remco

[axunonb]

Hi! Would you agree that as of RFC5555 section 3.3.4, a DATE property cannot have a timezone?
That's why we have this implementation, never mind the implementation in v4.

[RemcoBlok]

Hi! I think that section is about a DATE value, not a DATE property. When I look at the DTSTART and DTEND properties, I see they can have either a DATE or DATE-TIME value, but also parameters like TZID. It is not clear to me that you cannot use a TZID parameter with a DATE value. So I think that you can use a TZID parameter with a DATE value.

[axunonb]

A certain evidence could be, that Google Calendar and Microsoft Outlook don't add a timezone to all-day events as well. Just double-checked that this is the case.
So we're confident that the implementation in v5 is compliant to RFC5545, while adding a timezone is not.
When a timezone should apply, a DATE-TIME value type is to be used instead of DATE.

BEGIN:VCALENDAR
PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN
VERSION:2.0
METHOD:PUBLISH
X-MS-OLK-FORCEINSPECTOROPEN:TRUE
BEGIN:VEVENT
CLASS:PUBLIC
CREATED:20250208T095053Z
DESCRIPTION: \n
DTEND;VALUE=DATE:20250204
DTSTAMP:20250208T095053Z
DTSTART;VALUE=DATE:20250203
LAST-MODIFIED:20250208T095053Z
PRIORITY:5
RRULE:FREQ=WEEKLY;COUNT=25;BYDAY=MO
SEQUENCE:0
SUMMARY;LANGUAGE=en:Test all-day event
TRANSP:TRANSPARENT
UID:040000008200E00074C5B7101A82E0080000000040B8BBE8157ADB01000000000000000
	0100000002B895833F77B2A4EA69F2887A3F5A198
X-MICROSOFT-CDO-BUSYSTATUS:FREE
X-MICROSOFT-CDO-IMPORTANCE:1
X-MICROSOFT-DISALLOW-COUNTER:FALSE
X-MS-OLK-CONFTYPE:0
BEGIN:VALARM
TRIGGER:-PT1080M
ACTION:DISPLAY
DESCRIPTION:Reminder
END:VALARM
END:VEVENT
END:VCALENDAR

[axunonb]

To fully address your use case: If you want the all-day event to be kind of associated with a specific timezone, you can add a default VTIMEZONE to the calendar. This might have the same effect as the non-compliant TZID added to a DATE value type.
Note, however, that adding a VTIMEZONE component to an iCalendar file generally has no effect on all-day events because they are designed to be timezone-independent. The DATE value type, means the event spans from midnight to midnight in the local time of the calendar application, regardless of the timezone settings.

[RemcoBlok]

Happy to discuss and explore solutions.

With a default timezime for the calendar you cannot have one all-day event in GMT and another all-day event in PST and my application figuring out which hours overlap.

All that should be independent of the local system timezone. I can run the application on a developer PC in CET and my colleague on their developer PC in EST and a (build) server in the cloud run the application in UTC. Was it really the intention of the icalendar standard to assume the local system timezone for an all-day event where ever that may be?

A timezone for an all-day event may not have any effect in ical.net itself, but is an essential piece of information my application wants to persist.

But perhaps, as you suggest, I should not use a DATE, but a DATE-TIME. In V4 an event would only be an all-day event if the Start did not have time component. In V5 can I specify an all-day event using a Start with a time component (always midnight)?

When specifying a time component, how can I indicate when I want to apply one-day Period sementics vs 24-hour Duration semantics (I'm using NodaTime's definition of Period vs Duration here)? For one-day Period semantics I must create the event using a one-day ical.net Duration, and for 24-hour Duration semantics I must create the event using an End that is 24 hours after the Start. I seem to recall reading that ical.net determinies the effective duration (using either End or Duration) and if that is (integer values of ) one day it will apply one-day Period sementics, leaving the programmer no way to indicate 24-hour Duration semantics, right? Knowing whether to apply one-day Period sementics vs 24-hour duration sementics is especially relevant with recurring all-day events and generating occurrences after daylight-saving transitions? For daylight-saving transitions you must know the timezone.

[minichma]

The differences between 24h vs 1d semantics have been addressed in #680. You can specify 24h (aka 'exact') semantics by specifying the duration via DTEND or via a time-only Duration (e.g. Duration.FromHours(24)). You can specify 1d (aka 'nominal') semantics via a date-only Duration (e.g. Duration.FromDays(1)).

Regarding DATE with TZID the RFC is quite clear in section 3.2.19:

The "TZID" property parameter MUST NOT be applied to DATE properties and DATE-TIME or TIME properties whose time values are specified in UTC.

[RemcoBlok]

Ah thank you for clarifying! So the answer then is, to associate a timezone to an all-day event you must create an event with a Start with a DATE-TIME value and TZID and with a Duration of 1 day (not 24 hours) and without an End. Thanks!

[RemcoBlok]

Is it posiible to update the CalendarEvent.IsAllDay property to

bool isAllDay = calendarEvent.Start.HasTime == false ||
                calendarEvent.Start.Time == TimeOnly.MinValue &&
                calendarEvent.Duration != null &&
                calendarEvent.Duration.Value.HasTime == false;

[minichma]

Yes, I think its certainly time for a 5.0 prerelease, so people can start experimenting with it. We can keep it a prerelease for some time and polish the API based on users feedback. By naming it prerelease, its clear, that the API can still change.

[bizinbarefeet]

I'm not sure if this is related but when we try v5 prerelease we get an error referencing Duration.Days

(we deal in daily durations as part of hotel calendar syncing)

Whats the transition for this please?

[minichma]

@bizinbarefeet Please be more precise on what your issue is. Consider opening an issue and please provide a reproducer!

[RemcoBlok]

@RemcoBlok Since you have already migrated to v5, is there by any chance some kind of migration guide you could share?

For me the biggest changes I had to make for migrating to V5 were

• Remove all the workarounds for issues in v4. Happy to say that none of the workarounds were required anymore in V5.
• Associate a timezone to an all-day event as outlined above. Basically use nominal durations instead of exact durations.
• Exception dates no longer require programming with PeriodList and Period. Much easier to program with the new ExceptionDates class.
• RecurrencePattern.Until is now a nullable CalDateTime instead of a non-nullable DateTime (removing the default value MinValue).
• RecurrencePattern.Count in now a nullable int (removing the default MinValue)

Some more thoughts:

With RecurrencePattern.Until now being a nullable CalDateTime instead of a non-nullable DateTime and with CalDateTime being a class, not a struct, the compiler did not make this nullability immediately obvious. Making CalDateTime a struct would make this nullability more obvious.

Also, due to the implicit operator on CalDateTime to implicitly convert a DateTime to a CalDateTime the compiler did not make it immediately obvious I could now construct a CalDateTime and assign that to RecurrencePattern.Until instead of a DateTime.

Regarding class vs struct: Net DateTime, DateTimeOffset, TimeSpan, DateOnly, TimeOnly and NodaTime types are structs. CalDateTime is a class, not a struct, and as such nullability behaves like it does with a class, not a struct. CalDateTime could be a struct as it does not use inheritance from a base class. The new Duration is already a struct. Occurrence could also be a struct. Occurrence.Period should perhaps be a new Interval struct instead of the Period class.

A question:

Has anything changed in V5 regarding inclusive/exclusive semantics for the startTime and endTime parameters for the Calendar.GetOccurrences<CalendarEvent>() methods? Can you clarify exactly how the startTime and endTime parameters apply to the Occurrence.Period?
Is it startTime <= Occurence.Period.StartTime && Occurence.Period.StartTime < endTime?
Or is it startTime <= Occurence.Period.StartTime && Occurence.Period.StartTime <= endTime?
Or is it startTime <= Occurence.Period.EndTime && Occurence.Period.StartTime < endTime?
Or is it startTime <= Occurence.Period.EndTime && Occurence.Period.StartTime <= endTime?
I'll raise a separate issue for some behaviour I observe that I do not understand.

[minichma]

@RemcoBlok Great feedback, much appreciated!

Also, due to the implicit operator on CalDateTime to implicitly convert a DateTime to a CalDateTime

Fully agree, the implicit conversion should be removed. Would you please create an issue (or better: a PR) for that?

Regarding class vs struct

Fully agree, that those types should be structs. Has been discussed several times. All that has historic reasons. CalDateTime has already been decoupled from the previous type hierarchy it had in v4, which is a prerequisite, but changing to struct will still be quite some work that I'm not sure, resources are available for at this time. But anybody would be greatly welcome to work on that.

Perhaps the public Period Occurrence uses should be a different Period than the Period ExceptionDates uses internally?

Probably yes. Generally speaking it would be good to separate the types that represent the model from those that are used for evaluation and arithmetics, because then the model types could hold additional information from the parsed input, maybe even inconsistent one (e.g. DATE with TZID), while the eval types would be clean, consistent, mostly structs, ... Also something I discussed with @axunonb before, but which seems to be out of scope for v5. I'm pretty sure, anybody working on that for v6 would be greatly welcome.