All model types are immutable records with init properties; change one with with. Lists are
IReadOnlyList<T> and are not copied, so do not mutate a list after handing it to a record.
IcalDocument is one VCALENDAR: ProdId, Method (an ItipMethod, or null for a plain calendar object) and
Components. IcalComponent is one VEVENT, VTODO or VJOURNAL, chosen by Kind.
| Member | Property | Notes |
|---|---|---|
Uid |
UID |
Yours; written verbatim, TEXT-escaped. |
Sequence |
SEQUENCE |
Yours; never bumped by the library. |
RecurrenceId |
RECURRENCE-ID |
Marks a modified occurrence. A DATE value is written with VALUE=DATE, a wall-clock value with the series TZID. A parsed line kept verbatim (below) is written until this value is changed. |
DtStamp |
DTSTAMP |
Falls back to Start; omitted when both are null. |
Start, End |
DTSTART, DTEND / DUE |
Instants. End is DTEND for an event, DUE for a to-do, and not written for a journal. |
IsAllDay |
VALUE=DATE |
Writes DTSTART/DTEND as dates. |
TimeZone |
TZID |
The zone a recurring series is written in, or the zone a parsed DTSTART carried. |
Summary, Description, Location, Comment |
SUMMARY, DESCRIPTION, LOCATION, COMMENT |
TEXT. |
DescriptionDerived |
DESCRIPTION;DERIVED=TRUE |
RFC 9073: the plain text was derived from a richer description. |
Organizer, OrganizerName |
ORGANIZER;CN=…:mailto:… |
|
Url |
URL |
A URI, written verbatim (RFC 5545 §3.8.4.6). A parsed URL with a space or control character is null here and kept verbatim. |
Categories |
CATEGORIES |
One line, comma-separated. |
BusyStatus |
TRANSP and X-MICROSOFT-CDO-BUSYSTATUS |
Busy, Free, Tentative, OutOfOffice, WorkingElsewhere; events only. |
IsPrivate |
CLASS:PRIVATE |
|
IsCancelled |
STATUS:CANCELLED |
Another parsed STATUS is kept verbatim and written while this stays false. |
Recurrence |
RRULE |
The modelled subset, below. IsRecurring and RecurrenceRuleText (read-only) report any rule. |
Attendees |
ATTENDEE |
Below. |
Conferences |
CONFERENCE |
Below. |
Alarms |
VALARM |
Below. |
Properties |
any | Typed extra properties, below. Written only. |
UnknownProperties |
any | Content lines the model does not cover, verbatim. |
OverrideComponents |
VEVENT blocks |
Modified occurrences written after this component. Written only. |
On parse, every VEVENT, VTODO and VJOURNAL in the calendar becomes its own IcalComponent, modified
occurrences included (they carry RecurrenceId); OverrideComponents is not populated.
IcalAttendee carries Address, DisplayName (CN), Role (ROLE: Required, Optional, NonParticipant),
ParticipationStatus (PARTSTAT: NeedsAction, Accepted, Tentative, Declined), Rsvp (RSVP=TRUE|FALSE, omitted
when null) and UserType (CUTYPE: Individual, Group, Resource, Room, Unknown, omitted when null).
IcalConference(Uri) with Features (FEATURE: Audio, Chat, Feed, Moderator, Phone, Screen, Video) and Label
(LABEL), written as CONFERENCE;VALUE=URI;FEATURE=…;LABEL=…:uri (RFC 7986 §5.11). The URI is written verbatim
and refused if it contains a space or a control character. A parsed CONFERENCE with any other feature or
parameter (for example LANGUAGE) stays verbatim in UnknownProperties.
IcalAlarm is a display alarm: TriggerBeforeStart (written as a negative duration,
TRIGGER;RELATED=START:-PT15M; a negative value triggers after the start and is written PT5M), Description and
an optional Uid (RFC 9074). TimeSpan.MinValue is refused when assigned; sub-second parts are not written. A
parsed alarm is typed only when it is exactly that shape: ACTION:DISPLAY, a start-relative trigger without an
explicit + that fits a TimeSpan, a description, and nothing else but a UID. Any other alarm (audio or email,
repeating, absolute, RELATED=END, acknowledged, snoozed) stays verbatim in UnknownProperties, its BEGIN:VALARM
and END:VALARM lines included. A BEGIN:VALARM that is never closed is not an alarm: it is kept, and the lines
after it are read as the component's own, as 1.1.x read them.
IcalRecurrenceRule holds Frequency (Daily, Weekly, Monthly, Yearly), Interval, Count or Until (UTC), and
ByDay (weekdays without an ordinal). A parsed RRULE with a FREQ of DAILY to YEARLY is always read into
Recurrence, as 1.1.x read it: the parts the record holds are taken and the rest (BYMONTHDAY, BYSETPOS,
BYMONTH, WKST, RSCALE, the ordinal weekdays of 1MO or -1FR) is not represented. A DATE UNTIL includes
its whole date: the date itself for an all-day component, otherwise the last second of that date in DTSTART's
zone (UTC when it has none). With several RRULE lines the last is read, as 1.1.x did. When BuildRRule would not
write the line back exactly (any of those parts, rule parameters, several RRULE lines), the lines are also kept
verbatim in UnknownProperties and written unchanged while Recurrence equals what the rule reads as; assigning a
different rule writes that rule and drops the kept lines, and setting Recurrence to null removes the rule. A rule
with another FREQ (HOURLY, MINUTELY) or a repeated part reads as null and is kept verbatim: it is written while
Recurrence is null and replaced when a rule is assigned. A kept rule is the sender's explicit rule, so moving
Start alone does not rewrite it.
IsRecurring tells whether a component repeats by any rule or RDATE, and RecurrenceRuleText is the RRULE
value the writer emits, so a reader can see a rule Recurrence cannot hold. Either way the component is written as
a series in its zone. EXDATE and RDATE are always kept verbatim. To write a full-grammar rule from code, put it
in UnknownProperties and set Recurrence to what it reads as (null when its FREQ is not daily to yearly).
The library does not expand a series into occurrences. IcalTimeZones.ParseInstant reads an EXDATE or
RECURRENCE-ID value, and IcalTimeZones.ToUtc / ToLocal apply RFC 5545 §3.3.5 for the gap and the overlap,
for callers that expand a series themselves.
A TZID-qualified DTSTART, DTEND or DUE is read in its zone with the host's time zone database (IANA or
Windows ids; vendor-prefixed ids such as /mozilla.org/20050126_1/Europe/Berlin resolve to their last segment).
A time that occurs twice is the first occurrence; a time that does not occur takes the offset before the gap. A
TZID the host cannot resolve, and a floating time (no Z, no TZID), are read as UTC; the zone is not kept and
the value is written back in the Z form. A client's VTIMEZONE blocks are not read.
On the way out, a recurring component whose zone has a moving offset is written as DTSTART;TZID=… plus a
VTIMEZONE built from the host's TimeZoneInfo. A single occurrence, an all-day component, and a series in UTC or
in a zone that has read UTC since before the series started keep the Z form.
Properties takes IcalProperty(Name, Value, Kind) with Parameters (IcalParameter). Kind is
IcalValueKind.Text (TEXT-escaped) or IcalValueKind.Uri (verbatim, refused with a space or a control
character). Helpers: IcalProperty.StyledDescriptionHtml, IcalProperty.AltDescriptionHtml and
IcalProperty.ImageUri. The name must be an RFC 5545 token and cannot be BEGIN, END, METHOD or any property
the model writes (UID, RECURRENCE-ID, SEQUENCE, DTSTAMP, DTSTART, DTEND, DUE, SUMMARY,
DESCRIPTION, LOCATION, COMMENT, ORGANIZER, URL, CATEGORIES, TRANSP, X-MICROSOFT-CDO-BUSYSTATUS,
CLASS, STATUS, RRULE, ATTENDEE, CONFERENCE): a second COMMENT would be read back into Comment and
replace it, and a second copy of any other name would repeat a single-valued property. Typed properties are
written after the modelled ones; on parse they arrive in UnknownProperties.
IcalParameter has a Name and one or more Values. IcalParameter.Of("FEATURE", "AUDIO", "VIDEO") writes
FEATURE=AUDIO,VIDEO; each value is quoted only when it contains :, ; or , or starts or ends with
whitespace, and encoded with RFC 6868 (^ as ^^, a newline as ^n, " as ^'). ContentLine.Parse decodes the
same and reports each value of a multi-valued parameter through ParamValues(name); the token lists TYPE,
FEATURE and DISPLAY are split inside quotes too (TYPE="voice,home"). A single-valued parameter such as CN,
TZID or LABEL is one value, commas and surrounding spaces included (CN=Doe, John reads Doe, John).
A parse followed by a serialize keeps, exactly:
EXDATE, RDATE, ATTACH,GEO, PRIORITY, RELATED-TO, X- properties, and so on), and every nested component inside it (VALARM,VLOCATION, PARTICIPANT), in UnknownProperties;RRULE, a VALARM and a CONFERENCE that the model cannot hold exactly, verbatim;RECURRENCE-ID the writer would not reproduce exactly (RANGE=THISANDFUTURE, a TZID the series is notRecurrenceId;STATUS other than CANCELLED;URL or CONFERENCE the writer would refuse (a space or control character in the URI), verbatim, so aA line kept for a modelled property (RRULE, RECURRENCE-ID, STATUS, URL) is written only while the typed
value equals what the last such line reads as, null included. Assign a different value and it is written and the
kept lines dropped; set it to null and a line that reads as a value is dropped too, so an edit or a clear is never
overridden by what was parsed. A line that reads as null (a rule with FREQ=HOURLY, a URL with a space) is
written while the typed value stays null.
It normalizes, and does not keep:
LANGUAGE or ALTREP onSUMMARY, SENT-BY on ORGANIZER, and DELEGATED-TO, DELEGATED-FROM, MEMBER or SENT-BY on ATTENDEE;ROLE reads as Required, an unknown PARTSTAT (for exampleDELEGATED) as NeedsAction, an unknown CUTYPE as none, and CLASS values other than PRIVATE are dropped;mailto: URI, which is written back as mailto:;CATEGORIES lines, which are merged into one, and a repeated single-valued property, of which the last wins;TZID the host cannot resolve and a floating time, which are written back as UTC;PRODID and METHOD, such as NAME, COLOR or X-WR-CALNAME, andVEVENT, VTODO and VJOURNAL, which are skipped.VERSION:2.0 and CALSCALE:GREGORIAN are always written.