IcalFileException Class

Definition

Namespace: DataStandardizer.File.iCal

The exception thrown for iCalendar data that cannot be read or written: a content line that does not follow RFC 5545 §3.1, a BEGIN or END that is not matched, an unsupported VERSION, a calendar that breaks a rule the options do not accept, a property that cannot be written, a value a typed accessor cannot parse, an xCal or jCal document that is not valid, or a time zone that cannot be resolved.

Syntax

public sealed class IcalFileException : Exception

Remarks

Details of where the problem was found are held in the exception’s Data dictionary, under the keys of the nested static class IcalFileException.DataItemName. Each item is present only when it applies, so check with Data.Contains before reading it. Some exceptions carry no items at all: data that holds no VCALENDAR, an xCal document with no icalendar root element, and the time zone errors of IcalTimeZoneResolver and the VTIMEZONE rules.

catch (IcalFileException exception)
{
    if (exception.Data.Contains(IcalFileException.DataItemName.LineNumber))
    {
        var line = (long)exception.Data[IcalFileException.DataItemName.LineNumber]!;
    }
}

When reading can continue. For IcalContentLineReader, a content line syntax error consumes the line, so reading can continue; a bare line feed that is not accepted, or a line longer than IcalOptions.MaxLineLength, cannot be recovered from. For IcalReader, a conformance problem (one with DiagnosticKind, found after END:VCALENDAR) discards that calendar and reading can continue; any other IcalFileException, including an unsupported VERSION, leaves the reader unable to continue. For the writers, a conformance problem means nothing of that calendar was written, and a content line error means nothing of that line was written.

Where each item comes from.

Thrown by Items present
IcalContentLineReader, and content line errors from IcalReader LineNumber, PhysicalLineNumber, and PropertyName once the name has been read.
IcalReader: BEGIN/END errors and a property outside a calendar LineNumber, PhysicalLineNumber, PropertyName, and ComponentPath when inside a component.
IcalReader, XcalReader, JcalReader: unsupported VERSION DiagnosticKind = UnsupportedVersion, PropertyName, ComponentPath, and the location items that reader gives: LineNumber and PhysicalLineNumber for .ics, LineNumber and LinePosition for xCal, JsonPath and BytePosition for jCal.
Any reader or writer of the component model: a conformance problem ComponentPath, DiagnosticKind, and LineNumber and PropertyName when the diagnostic has them.
IcalContentLineWriter, and content line errors from IcalWriter LineNumber (the number the line would have had in the output), and PropertyName once the property name is valid.
IcalContentLine.GetTextValue, IcalContentLineView.GetTextValue, and the typed accessors of the component model LineNumber, PhysicalLineNumber, PropertyName. The items are always present: for a property read from xCal, LineNumber is the line of the XML document and PhysicalLineNumber is 0; for one read from jCal or built in code, both are 0.
XcalReader LineNumber and LinePosition in the XML document where known, and PropertyName where it applies. For XML that is not well-formed, the XmlException is the inner exception.
JcalReader JsonPath and BytePosition, and PropertyName where it applies. For JSON that is not valid, BytePosition, LineNumber and LinePosition in the JSON document, with the JsonException as the inner exception.
JcalWriter LineNumber of the property’s source line, if it has one, and PropertyName.

Constructors

Constructor Notes
IcalFileException()  
IcalFileException(string message)  
IcalFileException(string message, Exception innerException)  

Fields

The constants of the nested static class IcalFileException.DataItemName, which are the keys of the items in Data.

Field Value Meaning
BytePosition "BytePosition" A long: the 0-based offset, in bytes from the start of the data, of the JSON token at which the problem was found. A byte order mark at the start is counted. For data that is not valid JSON, the offset of the end of the last token read. JcalReader only.
ComponentPath "ComponentPath" A string: the path of the component in which the problem was found, such as VCALENDAR/VEVENT[3]. Each component under the calendar has a 1-based index among the components of the same name in its parent. Readers and writers of the component model only. See IcalDiagnostic.ComponentPath.
DiagnosticKind "DiagnosticKind" An IcalDiagnosticKind: the kind of conformance problem. Present only for a problem that IcalComponent.Validate also reports. Any of the six values can appear. InvalidComponentNesting and UnsupportedVersion always throw; the other four throw only when their IcalOptions accommodation is off.
JsonPath "JsonPath" A string: the path of the JSON value at which the problem was found, such as $[2][0][1][3] or $[1][3][1]['tzid']. JcalReader only, once the value has been read; a JSON syntax error has BytePosition instead.
LineNumber "LineNumber" A long: the 1-based number of the logical (unfolded) content line. For XcalReader, the line of the XML document. For JSON that is not valid, the line of the JSON document. For a writer’s content line error, the number the line would have had in the output.
LinePosition "LinePosition" A long: the 1-based position on the line of the XML document, where known (XcalReader); or, for JSON that is not valid, the 1-based position in bytes on the line of the JSON document (JcalReader).
PhysicalLineNumber "PhysicalLineNumber" A long: the 1-based number of the physical line on which the problem was found in .ics data. Not added by the xCal or jCal readers, but a typed accessor adds it, as 0, for a property that was not read from .ics data.
PropertyName "PropertyName" A string: the name of the property on the content line. Present only once the name has been read.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. JcalReader and JcalWriter, and so the BytePosition and JsonPath items, are available on netstandard2.0, netstandard2.1, and the .NET targets only; the constants themselves are on every target.

See also


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