Convert between .vcf, jCard and xCard
All three formats read into, and write from, the same card model, VcardCard. 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 |
|---|---|---|
.vcf (RFC 6350, and vCard 3.0 and 2.1) | VcardReader | VcardWriter |
| jCard, JSON (RFC 7095) | JcardReader | JcardWriter |
| xCard, XML (RFC 6351) | XcardReader | XcardWriter |
Applies to:
JcardReaderandJcardWriterneed .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.vcfand xCard aTextReaderorTextWriter.
.vcf to jCard
using DataStandardizer.File.vCard;
using (var reader = new VcardReader("contacts.vcf"))
using (var writer = new JcardWriter("contacts.json"))
{
writer.WriteCards(reader.ReadCards());
}
.vcf to xCard
using (var reader = new VcardReader("contacts.vcf"))
using (var writer = new XcardWriter("contacts.xml"))
{
writer.WriteCards(reader.ReadCards());
}
jCard to .vcf
using (var reader = new JcardReader("contacts.json"))
using (var writer = new VcardWriter("contacts.vcf"))
{
writer.WriteCards(reader.ReadCards());
}
xCard to jCard
using (var reader = new XcardReader("contacts.xml"))
using (var writer = new JcardWriter("contacts.json"))
{
writer.WriteCards(reader.ReadCards());
}
The other directions work the same way.
ReadCards reads one card at a time as WriteCards enumerates it, so a large document doesn’t have to fit in memory. The jCard and xCard writers finish the document when they are disposed, so dispose the writer before you read the output.
Older versions
jCard and xCard represent vCard 4.0 alone. A vCard 3.0 or 2.1 card read from .vcf is written in the canonical form of vCard 4.0, as VcardWriter writes it by default. Going the other way, a card read from jCard or xCard can be written as vCard 3.0 or 2.1 by setting WriteVersion on the VcardWriter’s options. See Convert between 4.0, 3.0 and 2.1.
var options = new VcardOptions { MaxLineLength = null, WriteVersion = VcardVersion.V3_0 };
using (var reader = new JcardReader("contacts.json"))
using (var writer = new VcardWriter("contacts.vcf", options))
{
writer.WriteCards(reader.ReadCards());
}
Convert asynchronously
Each writer’s WriteCardsAsync accepts the IAsyncEnumerable<VcardCard> that a reader’s ReadCardsAsync returns:
await using var reader = new VcardReader("contacts.vcf");
await using var writer = new JcardWriter("contacts.json");
await writer.WriteCardsAsync(reader.ReadCardsAsync(cancellationToken), null, cancellationToken);
See Read asynchronously.
Options and checks
Every reader and writer checks each card against RFC 6350 and its extensions, whatever the format. A card that a reader accepts only with an option, such as AllowMissingRequiredProperties, is refused by the writer unless you give it the same option:
var options = new VcardOptions { MaxLineLength = null, AllowMissingRequiredProperties = true };
using (var reader = new VcardReader("contacts.vcf", options))
using (var writer = new XcardWriter("contacts.xml", options))
{
writer.WriteCards(reader.ReadCards());
}
The options for content lines, such as AcceptBareLineFeed, have no meaning for jCard and xCard, which have no content lines. See Read non-compliant cards.
What a round trip keeps
Converting a vCard 4.0 card from one format to another and back keeps every property, parameter and value. It doesn’t keep:
- Layout: where
.vcflines 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. Property and parameter names come back in upper case, TEXT escaping is applied again, so
\Ncomes back as\n, BOOLEAN values come back in upper case, and the values ofTYPE,PIDandSORT-AScome back as one list, soTYPE=work;TYPE=voicecomes back asTYPE=work,voice. - The
VALUEparameter as written: after a trip through jCard or xCard, 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 jCard and Read and write xCard, along with how each part of vCard maps to each format.