The common model and the versioned interfaces
VcardCard is the object model of a card, the top layer of the package (see The layered model), and VcardReader and VcardWriter read and write it.
using (var reader = new VcardReader("contacts.vcf"))
{
foreach (var card in reader.ReadCards())
{
// FN is required from vCard 3.0, but a vCard 2.1 card can have N alone.
Console.WriteLine(card.FormattedNames.GetPreferred()?.Value ?? "(no name)");
}
}
vCard 4.0, 3.0 and 2.1 can be read and written. See Versions and canonical forms.
Common and versioned members
The versions of vCard are not additive. For example, vCard 4.0 has KIND, which earlier versions don’t, and vCard 3.0 has MAILER, which 4.0 doesn’t. So the model has two halves.
The common members are the public members of VcardCard and VcardProperty<TValue>. They cover every version, and each concept is held once, in a canonical form: the form of vCard 4.0 wherever 4.0 has an equivalent. A card of a version that can be read loads into these members, and SourceVersion records the version it was read from.
The versioned interfaces give one version’s shape. Each is implemented explicitly on the same object, so a view is not a copy, and a change through one is a change through the other.
IVcard40Card version40 = card.AsVersion40();
version40.Telephones.Add(new VcardTypedValue(new Uri("tel:+1-555-555-5555")));
The rules of a versioned interface, which each version follows:
- It exposes only the members its version defines, in that version’s shape.
- It doesn’t inherit from the interface of another version.
- It doesn’t expose the raw
Propertieslist or content lines, so code written against it is checked by the compiler. Unknown andX-properties are reached throughExtensionProperties, and unknown parameters throughExtensionParameters. - A getter gives the common value directly or adapts it, and a setter adapts back into the canonical form. For vCard 4.0 the canonical form is its own, so its members pass the value through as it is.
- It hides what its version can’t show. Reading is never lossy, so any card can be viewed as any version, including one read from another version.
Property wrappers and lists have versioned interfaces in the same way: IVcard40Property<TValue> and IVcard40PropertyList<TValue>, IVcard30Property<TValue> and IVcard30PropertyList<TValue>, and IVcard21Property<TValue> and IVcard21PropertyList<TValue>. AsVersion30() gives the IVcard30Card view, and AsVersion21() the IVcard21Card view.
The open list of properties
VcardCard.Properties holds every property in order, with its group and parameters, including unknown and X- properties, and including any whose value isn’t valid. The typed members read and change this list, so nothing is held twice. It doesn’t hold BEGIN, VERSION or END, which a reader takes in and a writer writes.
A typed member leaves out a property whose value isn’t valid, which it can only have if AllowInvalidValues let it be read, or if it was added to Properties directly. It also leaves out one with a CALSCALE other than gregorian, since RFC 6350 §5.8 says to ignore it.
Extensions
The extensions of vCard 4.0 have members of their own, and aren’t in ExtensionProperties. None of them exists in vCard 3.0 or 2.1.
| Standard | What it adds | Members |
|---|---|---|
| RFC 6473, RFC 6869 | KIND:application, KIND:device | VcardKind.Application, VcardKind.Device |
| RFC 6474 | BIRTHPLACE, DEATHPLACE, DEATHDATE | BirthPlace, DeathPlace, DeathDate |
| RFC 6715 | EXPERTISE, HOBBY, INTEREST, ORG-DIRECTORY, and the parameters LEVEL and INDEX | Expertise, Hobbies, Interests, OrganizationDirectories, and Level and Index on a property |
| RFC 8605 | CONTACT-URI, and the parameter CC on ADR | ContactUris, and CountryCode on a property |
| RFC 9554 | CREATED, GRAMGENDER, LANGUAGE, PRONOUNS, SOCIALPROFILE, and ten parameters | Created, GrammaticalGenders, DefaultLanguage, Pronouns, SocialProfiles, and members on a property such as ServiceType and Phonetic |
var hobbies = card.Hobbies.GetOrderedByIndex();
VcardLevel? level = hobbies[0].Level;
Iso3166Part1Alpha2Country? country = card.Addresses[0].CountryCode;
The LANGUAGE property of RFC 9554 is DefaultLanguage, because Languages is LANG, the languages that may be used for contact. JSContact itself (RFC 9553) isn’t implemented, and the JSPROP property and the JSPTR and JSCOMPS parameters of RFC 9555 are kept and written back like any unknown property or parameter.
The components of N and ADR
RFC 9554 adds components to N and ADR, and says what to do so that software that doesn’t know them can still read a card.
N (§2.2) | ADR (§2.1) | |
|---|---|---|
| Writing | A secondary surname also goes in the family names, and a generation in the honorific suffixes. | The new components are combined in the street address. |
| Reading | Ignore a value in those older components that is also in the new one: FamilyNamesExcludingSecondarySurnames, HonorificSuffixesExcludingGenerations. | Ignore the street address if HasDetailedComponents is true. |
SetName and Addresses.Add do the writing half, and WithBackwardCompatibleComponents does it for a value of your own. The RFC doesn’t say how to combine the components of an address, so give the address a street address if the order matters: one it already has is left alone. A line added to Properties is written as it is, and so is a value with a PHONETIC parameter, because §4.6 needs its related property to have a value in each of its components. A card that was read keeps its values as they were.
var name = VcardName.Parse("Doe;John;;;;Smith;Jr.".AsSpan(), VcardValueFormat.Text);
card.SetName(name); // N:Doe,Smith;John;;;Jr.;Smith;Jr.
Phonetic values
A PHONETIC property says how to pronounce another of the same name, which has the same ALTID and no PHONETIC (§4.6). Name gives the one without it, whichever comes first. SetName replaces every N, so to write a pair, add both lines to Properties.
foreach (var alternatives in card.Addresses.GetAlternatives())
{
var phonetic = alternatives.FirstOrDefault(address => address.Phonetic != null);
}
Derived values and identifiers
DERIVED=true says that a value is worked out from other properties, and RFC 9554 §4.4 says a client “MUST NOT update the property”. So a setter such as SetName throws InvalidOperationException on one. Software that works the value out again removes the instance first, with RemoveProperties.
PROP-ID identifies a property among those of the same name. An application “SHOULD assign a unique identifier”, and resolving a duplicate is “specific to the application” (§4.7), so Validate() doesn’t report one. GetDuplicatePropertyIds() finds them.
Writing to an older version
None of this exists in vCard 3.0 or 2.1, and VcardPropertyInfo.IsDefinedIn says so. Writing vCard 3.0 reports it as Lossy; see Versions and canonical forms.
Commas in URI values
RFC 6350 §3.4 says a comma in a value “MUST be escaped”, and its verified errata 3845 and 3846 apply that to URI values, so a card has GEO:geo:37.386013\,-122.082932. A System.Uri in the model has no escaping, and a writer adds it. The RFC still prints some values with a bare comma and many writers write them, so AcceptUnescapedCommasInUris lets a reader accept them. A GEO parameter on ADR is a quoted string, to which this doesn’t apply.
Preference and alternatives
GetPreferred and GetAlternatives find the preferred instance of a property and the alternatives among its instances. See PREF, PID and ALTID.
Groups
KIND:group cards list their members with MEMBER, and ResolveMembers looks them up by UID in a set of cards. A member may be something other than a card, such as a mailto URI, and nothing outside the set is looked up.
var cards = reader.ReadCards().ToList();
var members = group.ResolveMembers(cards);
Conformance
Validate() returns every problem in a card as a VcardDiagnostic. A problem in the card never throws, but an exception from a CharsetResolver of your own, which can be asked to resolve a CHARSET as the card is checked, isn’t caught, and Validate(version) checks a card by the rules of a version. The rules, and the options that accept a card that breaks one, are in Standards compliance by default.