The vCard

My MVC site will have a little bit of social networking in it. One of the requirements is to be able to export a contact into a vCard. vCard is an exchange format used like an electronic business card. It’s the format that is used by Outlook, Thunderbird, or even Apple’s iPhone when exchanging contacts. It’s an open standard, the latest version is 3.0 specified in RFC 2426. It’s been around for a while, too. The 3.0 specification was put out in 1998. It’s been 12 years, and not much as changed with the vCard. This specification was put out before XML came to true fruition, so it’s got a bit of an odd format. Here is an example of a vCard, with the bare minimum specified.

BEGIN:VCARD
VERSION:3.0
N:Jones;Kevin;George
FN:Kevin Jones
REV:2010-08-01T07-24-04Z-04:00
END:VCARD

It’s a set of “types” and values that are delimited by a colon. There can be optional parameters specified with the type as well, such as an indicator for special encoding rules. The types can be looked up in the documentation, but these are:

  • N: The name components.
  • FN: The Full Name. Possibly could be considered the Display Name.
  • REV: The revision. At minimum, the Date portion must be specified, such as “2010-08-01”. The Time portion and Offset portion are optional. The format requires that dates are padded with zeros. Like “08” instead of “8”.
  • BEGIN, END: Pretty obvious. The card must end and begin with these values.
  • VERSION: Also obvious. The version of the specification you are sticking to. See the RFC for notes on differences between 3.0 and 2.1.

My implementation sticks to the RFC’s design as close as possible, and tries to implement all features supported by vCard, including embedding binary objects (like a picture or sound clip). There are two important classes, the VCard class and the RFC2426VCardFormatter. I used the formatting engine built into .NET since people are familiar with it; and we can implement some cool features doing that. The VCard class is the card itself, and RFC2426VCardFormatter implements IFormatProvider and ICustomFormatter and converts a VCard instance to a string. Here is a sample:

   1: VCard card = new VCard


   2:                 {


   3:                     NameFamily = "Jones",


   4:                     NameGiven = "Kevin",


   5:                     NameMiddle = "George",


   6:                     NameFormatted = "Kevin Jones",


   7:                     JobTitle = "Team Lead",


   8:                     JobCompany = "Thycotic Software Ltd",


   9:                     JobRole = "Programmer",


  10:                     DateBirth = new DateTimeOffset(1987, 8, 7, 4, 30, 0, new TimeSpan(-5, 0, 0)),


  11:                     NameSort = "Jones",


  12:                     NameNickname = "Kev",


  13:                     Url = "http://www.thycotic.com/",


  14:                     Mailer = "Outlook 2010",


  15:                     Note = "Is a connoisseur of cheese." + Environment.NewLine + "And poor speller."


  16:                 };


  17: Console.Out.WriteLine(card);

the output will be:

BEGIN:VCARD
VERSION:3.0
N:Jones;Kevin;George
FN:Kevin Jones
SORT-STRING:Jones
NICKNAME:Kev
BDAY:1987-08-07T04-30-00Z-05:00
TITLE:Team Lead
ORG:Thycotic Software Ltd
ROLE:Programmer
MAILER:Outlook 2010
NOTE:Is a connoisseur of cheese.\nAnd poor speller.
URL:http://www.thycotic.com/
REV:2010-08-01T09-21-16Z-04:00
END:VCARD

The formatting engine supports just portions of the vCard object as well. Changing the Console.Out.WriteLine to

   1: Console.Out.WriteLine("{0:BEGIN;VERSION;N;FN;REV;END}",card);





Will only output the BEGIN, VERSION, N, FN, REV, and END portions of the vCard. A link to the code library is here. It’s not 100% implemented yet, but supports all of the features that Outlook and most other mailing software are going to care about, including the PHOTO type, addresses, emails, phone numbers, etc. The “AGENT” type may be the only one I never get around to implementing. See the XML comments for additional usage and functionality. Let me know if there are any bugs!



NOTE: If your browser insists that the ZIP file is a TGZ extension, just change it back to ZIP. Not sure why the MIME type is wrong.

2 thoughts on “The vCard”

  1. Dave,

    It’s my intention to get there, just looking for the time. I need to polish it up a little bit more before it goes from a hairbrained idea on a blog to an actual concept. Thorough unit test coverage is missing.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>