IcalOptions Class

Definition

Namespace: DataStandardizer.File.iCal

Options to configure the behaviour of an iCalendar reader or writer, and of recurrence expansion. The defaults follow RFC 5545. Each accommodation for common non-compliant input is a separate option, off by default. Pass an instance to a reader or writer constructor, or to a GetOccurrences overload.

.NET:

public sealed record IcalOptions

.NET Standard:

public sealed class IcalOptions

Remarks

On net10.0 the type is a record whose properties are init-only, so configure it with an object initializer or a with expression. On .NET Standard the type is a plain class whose properties are settable. Construct it with the implicit parameterless constructor and set the properties you need; the rest keep their defaults.

Options are checked when they are used, not when they are set. A reader or writer checks the options it uses in its constructor and throws ArgumentException for a value it does not accept. Recurrence expansion checks MaxRecurrenceIterations when it is called.

Where each option applies.

  • Reading .ics (IcalContentLineReader, IcalReader): AcceptBareLineFeed, AcceptByteOrderMark, AcceptMissingFinalLineBreak, MaxLineLength, Encoding.
  • Writing .ics (IcalContentLineWriter, IcalWriter): FoldLength, FoldWhitespace, LineBreak, Encoding.
  • Conformance, reading and writing (IcalReader, IcalWriter, XcalReader, XcalWriter, JcalReader, JcalWriter): AllowInvalidValues, AllowCardinalityViolations, AllowMissingRequiredProperties, AllowQuotedParameterValues, AllowUndefinedTimeZones. The content line reader and writer do not check conformance, so these do not affect them.
  • xCal: Encoding for reading and writing, and LineBreak for writing.
  • jCal: Encoding, which must be null or UTF-8.
  • Recurrence expansion (IcalRecurrenceRule.GetOccurrences and the GetOccurrences overloads of IcalEvent, IcalTodo and IcalJournal that take options): MaxRecurrenceIterations.

Any option not listed for a reader, writer or method is ignored by it.

Constructors

Constructor Notes
IcalOptions() Implicit parameterless constructor; all properties take their defaults.

Properties

On .NET Standard each property is get; set; instead of get; init;.

Property Signature Default Applies to Notes
AcceptBareLineFeed bool AcceptBareLineFeed { get; init; } false Reading .ics Accept a bare line feed as a line break, both to end a content line and in a fold. RFC 5545 §3.1 requires CRLF; when false, a bare line feed throws IcalFileException and the reader cannot continue. A bare carriage return is never a line break.
AcceptByteOrderMark bool AcceptByteOrderMark { get; init; } false Reading .ics Accept and skip a byte order mark at the start of the data. The icalstream rule of RFC 5545 §3.6 starts with BEGIN:VCALENDAR, and RFC 3629 §6 says a protocol that mandates UTF-8 should forbid the signature. When false, a byte order mark throws IcalFileException, even when Encoding has a preamble. It never selects the encoding. xCal and jCal readers ignore it.
AcceptMissingFinalLineBreak bool AcceptMissingFinalLineBreak { get; init; } false Reading .ics Accept a last content line with no line break. The contentline rule of RFC 5545 §3.1 ends with CRLF, including on the last line. When false, such a line throws IcalFileException. A writer always ends the last line with a line break.
AllowCardinalityViolations bool AllowCardinalityViolations { get; init; } false Reading and writing Accept a property that appears more often than RFC 5545 allows, or two properties that exclude each other, such as DTEND and DURATION in a VEVENT. When false, a reader rejects such a calendar and a writer refuses to write it, with IcalFileException. A typed accessor reads the first of the properties.
AllowInvalidValues bool AllowInvalidValues { get; init; } false Reading and writing Accept a property value that does not follow the syntax of its value type (RFC 5545 §3.3), or that breaks a rule tying it to its property: a VALUE parameter the property does not allow, or one it requires; a DATE-TIME that must be in UTC, such as the DTSTART and DTEND of a VFREEBUSY (RFC 5545 §3.8.2.4 and §3.8.2.2); a DTSTART of a STANDARD or DAYLIGHT observance that isn’t a DATE-TIME in local time (RFC 5545 §3.6.5); the UNTIL of a recurrence rule in such an observance that isn’t in UTC (RFC 5545 §3.3.10); date-times that must have the same value type as DTSTART; a DTEND or DUE that is in local time with no time zone when DTSTART isn’t, or the other way round, or that isn’t later in time than DTSTART (RFC 5545 §3.8.2.2 and §3.8.2.3); a RECURRENCE-ID whose value type, or whether it is in local time with no time zone, differs from the DTSTART of the recurring component in the calendar with the same UID (RFC 5545 §3.8.4.4); and a STATUS, TRANSP or CALSCALE value, in a component that defines it, outside the closed set of RFC 5545 §3.8.1.11, §3.8.2.7 or §3.7.1. A DTEND or DUE with a time zone is compared without expanding the rules of its VTIMEZONE, so one earlier than DTSTART by less than the spread of the time zone’s UTC offsets isn’t reported. Also covers the FMTTYPE parameter, which RFC 5545 §3.2.8 makes one type and subtype with no media type parameters, and which may appear only once; a parameter defined with one value in RFC 5545 §3.2 or RFC 7986 §6 that has more, such as CN=Doe, John, whose comma must be in a quoted string; and a parameter repeated on a property, where RFC 5545 §3.8 and RFC 7986 §5 say it “MUST NOT occur more than once”. When false, a reader rejects the calendar and a writer refuses to write it, with IcalFileException. When true, the value is kept as written, and a typed accessor such as IcalEvent.DtStart or IcalContentLine.GetFormatType throws IcalFileException when it reads it. For any other parameter that is repeated or has too many values, a typed accessor uses the first value.
AllowMissingRequiredProperties bool AllowMissingRequiredProperties { get; init; } false Reading and writing Accept a missing required property or component, such as the UID or DTSTAMP of a VEVENT, or the STANDARD or DAYLIGHT parts of a VTIMEZONE. A missing VERSION isn’t covered, since it says how the calendar is read (RFC 5545 §3.6 and §3.7.4), so the readers reject a calendar without one whatever this is; IcalWriter always writes VERSION:2.0, so it never refuses a calendar for lacking one. When false, a reader rejects such a calendar and a writer refuses to write it, with IcalFileException.
AllowQuotedParameterValues bool AllowQuotedParameterValues { get; init; } false Reading and writing Accept a value in double quotes for a parameter whose grammar has no quoted form, such as FMTTYPE="audio/basic". RFC 5545 §3.1 allows a quoted-string in general, but the rule for each parameter narrows that, and some leave it out: fmttypeparam = "FMTTYPE" "=" type-name "/" subtype-name in RFC 5545 §3.2.8 is one. The others are CUTYPE, ENCODING, FBTYPE, LANGUAGE, PARTSTAT, RANGE, RELATED, RELTYPE, ROLE, RSVP, TZID and VALUE in RFC 5545 §3.2, and DISPLAY and FEATURE in RFC 7986 §6, on any property. When false, a reader rejects such a calendar and a writer refuses to write it, with IcalFileException; IcalWriter also refuses a value it would have to quote, one with a :, ; or ,, on a line built in code. When true, the value is read without its quotes, and IcalWriter writes the parameter back as it was read, with them, and quotes a value built in code that needs it. jCal and xCal have no quoting, so their readers and writers accept such a value whatever this option is.
AllowUndefinedTimeZones bool AllowUndefinedTimeZones { get; init; } false Reading and writing Accept a TZID parameter that names a time zone the calendar has no VTIMEZONE for. RFC 5545 §3.2.19 requires one. When false, a reader rejects such a calendar and a writer refuses to write it, with IcalFileException.
Encoding Encoding? Encoding { get; init; } null Reading and writing The encoding of the data. Applies only when the reader or writer is created from a Stream or file path; with a TextReader, TextWriter or XmlReader it must be null, or the constructor throws ArgumentException. When null, a .ics reader uses strict UTF-8 (the default charset of RFC 5545 §3.1.4), so data that isn’t valid UTF-8 throws IcalFileException, and a .ics or xCal writer writes UTF-8 without a byte order mark. A .ics reader uses another encoding with its own fallback, so Encoding.UTF8 replaces invalid data with U+FFFD; a byte order mark never selects the encoding, and is accepted only by AcceptByteOrderMark. An xCal reader with null lets the XML reader detect the encoding. jCal accepts only null or UTF-8, and throws ArgumentException for anything else.
FoldLength int FoldLength { get; init; } 75 Writing .ics The length, in octets of the UTF-8 encoding and not counting the line break, at which a writer folds content lines. 75 is the length RFC 5545 §3.1 recommends. A fold never splits a character. The minimum is 4, the longest UTF-8 sequence; a continuation line that starts with a 4-octet character is then one octet longer. A smaller value makes the writer constructor throw ArgumentException.
FoldWhitespace char FoldWhitespace { get; init; } ' ' Writing .ics The white space at the start of each continuation line of a folded line: a space or a horizontal tab, the two RFC 5545 §3.1 allows. Any other character makes the writer constructor throw ArgumentException. A reader accepts both regardless.
LineBreak string LineBreak { get; init; } "\r\n" Writing .ics and xCal The line break a writer ends each physical line with, including the lines of a fold. RFC 5545 §3.1 requires CRLF. "\n" may be chosen for consumers that expect it. Any other value makes the writer constructor throw ArgumentException. Never depends on Environment.NewLine. For reading, see AcceptBareLineFeed.
MaxLineLength int? MaxLineLength { get; init; } null Reading .ics The maximum length, in characters and not counting the line break, of a logical (unfolded) content line. null means no limit, since RFC 5545 sets none. The reader keeps each logical line in memory, so set a limit when reading untrusted data. A longer line throws IcalFileException and the reader cannot continue, and so does a line with more folds than the limit. A value less than 1 makes the reader constructor throw ArgumentException.
MaxRecurrenceIterations int MaxRecurrenceIterations { get; init; } 100000 Recurrence expansion The number of consecutive periods a recurrence rule may step through without producing an occurrence before expansion gives up with InvalidOperationException. A period is one step of the rule’s frequency, such as a year for FREQ=YEARLY; a run of periods the rule skips as a whole counts as one. This stops a rule that can never match, such as FREQ=SECONDLY;BYMONTH=2;BYMONTHDAY=30, from running for a very long time. The default is far more than any rule that can match needs. A value less than 1 makes the call throw ArgumentException.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. IcalOptions is a record with init-only properties on the net10.0 build, and a plain class with settable properties on the netstandard1.1, netstandard2.0, and netstandard2.1 builds. The nullable annotation on Encoding applies to the netstandard2.1 and net10.0 builds.

See also


This site uses Just the Docs, a documentation theme for Jekyll.