Skip to content

Home

Jump to bottom
Folker Kinzel edited this page Oct 21, 2024 · 21 revisions

Getting Started

(This is a quick guide to get you started. You can find detailed information in the project reference.)

Simple example

public static void WritingAndReadingVCard(string filePath)
{
    VCard vCard = VCardBuilder
            .Create()
            .NameViews.Add(NameBuilder
                .Create()
                .AddGivenName("Susi")
                .AddFamilyName("Sonntag")
                          )
            .NameViews.ToDisplayNames(NameFormatter.Default)
            .GenderViews.Add(Sex.Female)
            .Phones.Add("+49-321-1234567",
                         parameters: p =>  p.PhoneType = Tel.Cell
                       )
            .EMails.Add("[email protected]")
            .EMails.Add("[email protected]")
            .EMails.SetPreferences()
            .BirthDayViews.Add(1984, 3, 28)
            .VCard;

    // Save vCard as vCard 3.0:
    // (You don't need to specify the version: Version 3.0 is the default.)
    Vcf.Save(vCard, filePath);

    // Load the VCF file. (The result is IList<VCard> because a VCF file may contain
    // many vCards.):
    IList<VCard> vCards = Vcf.Load(filePath);
    vCard = vCards[0];

    // Use Linq and/or extension methods to query the data:
    string? susisPrefMail = vCard.EMails.PrefOrNull()?.Value;
}

The VCF file the method creates is:

BEGIN:VCARD
VERSION:3.0
REV:2024-10-12T14:10:09Z
UID:27d7b637-b806-430a-a345-d6604406fec8
FN:Susi Sonntag
N:Sonntag;Susi;;;
X-GENDER:Female
BDAY;VALUE=DATE:1984-03-28
TEL;TYPE=CELL:+49-321-1234567
EMAIL;TYPE=INTERNET,PREF:[email protected]
EMAIL;TYPE=INTERNET:[email protected]
END:VCARD

The usage of the namespaces

// Publish this namespace - it contains the VCard class,
// the VCardBuilder class, and the VCF class:
using FolkerKinzel.VCards;

// It's recommended to publish also this namespace -
// it contains useful extension methods:
using FolkerKinzel.VCards.Extensions;

// This namespace contains often used enums. Decide
// yourself whether to publish this namespace or to use
// a namespace alias.
using FolkerKinzel.VCards.Enums;

// Since VCardBuilder exists, the model classes normally
// don't need to be instantiated in own code:
// using FolkerKinzel.VCards.Models;

The data model

The data model used by this library is aligned to the vCard 4.0 standard (RFC 6350). This means that every vCard of version 2.1 and 3.0 is internally converted to vCard 4.0. When saved and serialized they are converted back.

The VCard class

A VCF file consists of one or more vCards. The content of a vCard is represented by the VCard class.

The VCardProperty class

A vCard consists of several "properties". Accordingly the data model of the VCard class is built on classes that are derived from VCardProperty.

VCardProperty exposes the following members:

public abstract class VCardProperty
{
    public string? Group { get; set; }

    public ParameterSection Parameters { get; }

    public virtual object? Value { get; protected set; }
}

This reflects the structure of a data row in a VCF file:

    group1.TEL;TYPE=home,voice;VALUE=uri:tel:+49-123-4567

In this example corresponds

  • group1 to VCardProperty.Group,
  • TEL;TYPE=home,voice;VALUE=uri to VCardProperty.Parameters and
  • tel:+49-123-4567 to VCardProperty.Value.

(Classes derived from VCardProperty hide the generic implementation of VCardProperty.Value in order to return derived classes instead of System.Object?.)

Naming conventions

Most properties of the VCard class are collections. It has to do with that many properties are allowed to have more than one instance per vCard (e.g. phone numbers, e-mail addresses). Such properties are named in Plural.

A special feature are properties whose name ends with "Views": These are properties that actually is only one instance allowed, but vCard 4.0 allows to have different versions of that single instance (e.g., in different languages). The same AltID parameter has to be set on each instance.

Most classes derived from VCardProperty implement IEnumerable<T> in order to be assignable to collection properties without having to be wrapped in an Array or List.

Use Linq and the built-in extension methods when querying the data.

Efficient building and editing of VCard instances using VCardBuilder

The VCard data model consists of numerous classes. Fortunately, you only need one to create and edit VCard instances: VCardBuilder provides a fluent API, which handles all the complicated operations in the background.

Learn more about this important class.

Parsing and serializing VCF files using the Vcf class

The Vcf class is a static class that contains a lot of methods for serializing and parsing VCard objects to or from VCF files.

Extension methods

The namespace FolkerKinzel.VCards.Extensions contains several extension methods that makes working with VCard objects more efficient and less error prone. It's recommended to publish this namespace when working with this library.

The methods are helpful in the following cases:

  • Most of the enums are Flags enums and most of the .NET properties with enum Types use the Nullable<T> variant of these enums. Extension methods help to savely evaluate and manipulate these nullable enum values.
  • The .NET data types for date and time (such like DateOnly or DateTimeOffset) are not fully compliant with the date-time information defined by the vCard standard. Extension methods for these data types help to overcome these issues.
  • Most of the properties of the VCard class are of a specialized Type of IEnumerable<VCardProperty?>?. Extension methods encapsulate most of the necessary null checking and Linq operations that are needed to retrieve the relevant data from these properties, or to store something there.
  • Some operations work with collections of VCard objects (e.g., saving several VCard objects together in a common VCF file). Extension methods allow these operations to be performed directly on these collections.

The vCard 4.0 data synchronization

With the vCard 4.0 standard a data synchronization mechanism using PID parameters and CLIENTPIDMAP properties has been introduced. For this to work fully automatically, only two lines of code are required.

Learn more

Handling of incompliant data

Parse errors, caused by not well-formed VCF files, are silently ignored by the library: It reads as much as it can from such files.

When converting from a higher vCard standard to a lower one, not all data is compliant. To minimize data loss, the library tries to preserve incompliant data using well-known x-name properties. The usage of such x-name properties can be controlled with the Opts enum.

Reading the project reference

At the GitHub Releases page there is a detailed project reference to each version of the Nuget package as CHM file in the Assets. On some systems the content of this CHM file is blocked. Before opening the file right click on the file icon, select Properties, and check the "Allow" checkbox - if it is present - in the lower right corner of the General tab in the Properties dialog.

Uppercase words, which are often found at the beginning of the documentation for a .NET property, are identifiers from the vCard standard. Digits in brackets that can be found at the end of the documentation for a .NET property, e.g., (2,3,4), describe which vCard standard the content of the .NET property is compatible with.

The digits have the following meaning:

  • 2: vCard 2.1,
  • 3: vCard 3.0
  • 4: vCard 4.0

Documents of the vCard standard

The vCard standard is defined in the following documents:

Extensions of the standard describe, e.g., the following documents:

Clone this wiki locally