vCardLib.dll 6.2.0-beta.0

vCardLib

vCardLib is a .NET library for reading and writing vCard (.vcf) contacts. It targets .NET Standard 1.3 and .NET Standard 2.0 and supports vCard 2.1, 3.0, and 4.0.

Documentation site: bolorundurowb.github.io/vCardLib

Deprecation notice

The .NET Standard 1.3 target is scheduled to be removed in a future major release. Prefer .NET Standard 2.0 or a current .NET (6+) for new projects.

Features

• Parse one or many contacts from a file path, a Stream, or a string (IEnumerable<vCard>).
• Serialize a single vCard or a collection to a string, with an optional output version override.
• Line unfolding when reading: a physical line that begins with a space or tab is merged into the previous line (RFC-style folding). For vCard 2.1, a line ending with = is also merged with the next line (quoted-printable-style continuation).
• Rich vCard model: names, formatted name, phones, emails, addresses, photos, categories, dates, gender, kind, URLs, timezone, geo, custom X- properties, and more (see vCardLib.Models).

Installation

Package Manager

Install-Package vCardLib.dll

.NET CLI

dotnet add package vCardLib.dll

The NuGet package id is vCardLib.dll. The latest published version is shown on the badge above.

Usage

using vCardLib.Deserialization;
using vCardLib.Enums;
using vCardLib.Models;
using vCardLib.Serialization;

Deserialization

From a file

IEnumerable<vCard> contacts = vCardDeserializer.FromFile(@"C:\contacts\people.vcf");

From a stream

// Encoding is chosen from a BOM when possible; the stream must be readable and seekable
// so the BOM probe can rewind (see FileDataHelpers.GetEncoding).
IEnumerable<vCard> contacts = vCardDeserializer.FromStream(stream);

From a string

FromContent requires, in order:

1. Non-whitespace input.
2. The text must start with BEGIN:VCARD and end with END:VCARD (exact token match; leading or trailing whitespace is not stripped). A UTF-8 BOM at the start will cause the begin check to fail unless you remove it first.
3. A VERSION property must appear in the payload.

var vcf = @"BEGIN:VCARD
VERSION:2.1
N:Doe;John;;;
FN:John Doe
END:VCARD";

IEnumerable<vCard> contacts = vCardDeserializer.FromContent(vcf);

Serialization

Only properties you set are written. Line breaks follow Environment.NewLine (platform default), not forced CRLF.

Single card

var card = new vCard(vCardVersion.v2)
{
    FormattedName = "John Doe"
};
string text = vCardSerializer.Serialize(card);
// Example (Windows): lines separated by \r\n
// BEGIN:VCARD
// VERSION:2.1
// FN:John Doe
// END:VCARD

Version override (emit another vCard version from the same in-memory card)

string asV4 = vCardSerializer.Serialize(card, vCardVersion.v4);

Multiple cards

string bundle = vCardSerializer.Serialize(new[] { card1, card2 });

API summary

Versions: use enum members vCardVersion.v2, vCardVersion.v3, and vCardVersion.v4 (not V2 / V4).

vCard 2.1 note: NICKNAME is not written for v2 output (not part of RFC 2426); other versions emit it when NickName is set.

Contributors

Thanks to @bolorundurowb, @crowar, @rmja, and @JeanCollas.

License

MIT. See LICENSE.