Convert between .ics, jCal and xCal
All three formats read into, and write from, the same component object model: IcalCalendar, IcalEvent and so on. So to convert, read with the reader for one format and write with the writer for another. There is no separate converter.
| Format | Reader | Writer |
|---|---|---|
.ics (RFC 5545) | IcalReader | IcalWriter |
| xCal, XML (RFC 6321) | XcalReader | XcalWriter |
| jCal, JSON (RFC 7265) | JcalReader | JcalWriter |
Applies to:
JcalReaderandJcalWriterneed .NET Standard 2.0 or later. They aren’t available on .NET Standard 1.1. The file-path constructors used below need .NET Standard 2.0 or later too; on .NET Standard 1.1, use aStream, or for.icsand xCal aTextReaderorTextWriter.
.ics to jCal
using DataStandardizer.File.iCal;
using (var reader = new IcalReader("calendar.ics"))
using (var writer = new JcalWriter("calendar.json"))
{
writer.WriteCalendars(reader.ReadCalendars());
}
.ics to xCal
using (var reader = new IcalReader("calendar.ics"))
using (var writer = new XcalWriter("calendar.xml"))
{
writer.WriteCalendars(reader.ReadCalendars());
}
jCal to .ics
using (var reader = new JcalReader("calendar.json"))
using (var writer = new IcalWriter("calendar.ics"))
{
writer.WriteCalendars(reader.ReadCalendars());
}
xCal to jCal
using (var reader = new XcalReader("calendar.xml"))
using (var writer = new JcalWriter("calendar.json"))
{
writer.WriteCalendars(reader.ReadCalendars());
}
The other directions work the same way.
ReadCalendars reads one calendar at a time as WriteCalendars enumerates it, so a large document doesn’t have to fit in memory. The jCal and xCal writers finish the document when they are disposed, so dispose the writer before you read the output.
Convert asynchronously
Each writer’s WriteCalendarsAsync accepts the IAsyncEnumerable<IcalCalendar> that a reader’s ReadCalendarsAsync returns:
await using var reader = new IcalReader("calendar.ics");
await using var writer = new JcalWriter("calendar.json");
await writer.WriteCalendarsAsync(reader.ReadCalendarsAsync(cancellationToken), null, cancellationToken);
See Read asynchronously.
Options and checks
Every reader and writer checks each calendar against RFC 5545, whatever the format. A calendar that a reader accepts only with an option, such as AllowUndefinedTimeZones, is refused by the writer unless you give it the same option:
var options = new IcalOptions { AllowUndefinedTimeZones = true };
using (var reader = new IcalReader("feed.ics", options))
using (var writer = new JcalWriter("feed.json", options))
{
writer.WriteCalendars(reader.ReadCalendars());
}
What a round trip keeps
Converting from one format to another and back keeps every component, property, parameter and value. It doesn’t keep:
- Layout: where
.icslines were folded, XML white space, comments and namespace prefixes, or JSON formatting and the order of an object’s keys. - Spelling: a few values come back with the same meaning but spelled differently. For example, TEXT escaping is applied again, so
\Ncomes back as\n, and BOOLEAN values come back in upper case. - The
VALUEparameter as written: after a trip through jCal or xCal, aVALUEparameter comes back after the property’s other parameters, and one that names the property’s default type doesn’t come back at all.
The full lists are in Read and write xCal and Read and write jCal, along with how each part of iCalendar maps to each format.