FolkerKinzel.VCards
VCard
Provides a fluent API for building and editing VCard objects.
Definition
Namespace: FolkerKinzel.VCards
Assembly: FolkerKinzel.VCards (in FolkerKinzel.VCards.dll) Version: 8.0.1+a91cc3f0fd39aeb548e16006a60ca9dd10a304a2
Assembly: FolkerKinzel.VCards (in FolkerKinzel.VCards.dll) Version: 8.0.1+a91cc3f0fd39aeb548e16006a60ca9dd10a304a2
C#
public sealed class VCardBuilderVB
Public NotInheritable Class VCardBuilderC++
public ref class VCardBuilder sealedF#
[<SealedAttribute>]
type VCardBuilder = class end- Inheritance
- Object VCardBuilder
Remarks
The properties of the VCardBuilder class have the same names as those
of the VCard class. Each of these properties gets a struct that provides
methods to edit the
corresponding VCard property. Each of these methods return the
VCardBuilder instance so that the calls can be chained.
Example
C#
using FolkerKinzel.VCards;
using FolkerKinzel.VCards.Enums;
using FolkerKinzel.VCards.Extensions;
using FolkerKinzel.VCards.Models;
namespace Examples;
public static class VCardExample
{
private const string v2FileName = "VCard2.vcf";
private const string v3FileName = "VCard3.vcf";
private const string v4FileName = "VCard4.vcf";
private const string underLine = "----------";
private const string photoFileName = "Example.jpg";
public static void WritingAndReadingVCard(string directoryPath)
{
// Registering the executing application with the VCard class is a technical requirement
// when using the data synchronization mechanism introduced with vCard 4.0 (PID and
// CLIENTPIDMAP). To do this, call the static method VCard.RegisterApp with an absolute
// Uri once when the program starts. (UUID URNs are ideal for this.)
VCard.RegisterApp(new Uri("urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556"));
string v2FilePath = Path.Combine(directoryPath, v2FileName);
string v3FilePath = Path.Combine(directoryPath, v3FileName);
string v4FilePath = Path.Combine(directoryPath, v4FileName);
VCard vCard = InitializeTheVCardAndFillItWithData(directoryPath, photoFileName);
// Implements ITimeZoneIDConverter to convert IANA time zone names to UTC-Offsets.
// (See the implementation as separate example.)
ITimeZoneIDConverter tzConverter = new TimeZoneIDConverter();
// Save vCard as vCard 2.1:
Vcf.Save(vCard, v2FilePath, VCdVersion.V2_1, tzConverter);
// Save vCard as vCard 3.0:
// You don't need to specify the version: Version 3.0 is the default.
Vcf.Save(vCard, v3FilePath, tzConverter: tzConverter);
// Save vCard as vCard 4.0. (A time zone converter is not needed):
Vcf.Save(vCard,
v4FilePath,
VCdVersion.V4_0,
options: VcfOpts.Default.Set(VcfOpts.SetPropertyIDs));
// Load vCard:
vCard = Vcf.Load(v3FilePath)[0];
WriteResultsToConsole(vCard);
///////////////////////////////////////////////////////////////
static VCard InitializeTheVCardAndFillItWithData(string directoryPath, string photoFileName)
{
// Creates a small "Photo" file for demonstration purposes:
string photoFilePath = Path.Combine(directoryPath, photoFileName);
CreatePhoto(photoFilePath);
return VCardBuilder
.Create()
.NameViews.Add(NameBuilder
.Create()
.AddPrefix("Prof.")
.AddPrefix("Dr.")
.AddGiven("Käthe")
.AddGiven2("Alexandra")
.AddGiven2("Caroline")
.AddSurname("Müller-Risinowsky")
.AddGeneration("II.")
.Build(),
parameters: p => p.Language = "de-DE",
group: vc => vc.NewGroup())
.NameViews.ToDisplayNames(NameFormatter.Default)
.GenderViews.Add(Gender.Female)
.GramGenders.Add(Gram.Feminine, parameters: p => p.Language = "de")
.Organizations.Add("Millers Company", ["C#", "Webdesign"])
.Titles.Add("CEO")
.Photos.AddFile(photoFilePath)
.Phones.Add("tel:+49-321-1234567",
parameters: p =>
{
p.DataType = Data.Uri;
p.PropertyClass = PCl.Work;
p.PhoneType = Tel.Cell | Tel.Text | Tel.Msg | Tel.BBS | Tel.Voice;
}
)
.Phones.Add("tel:+49-123-9876543",
parameters: p =>
{
p.DataType = Data.Uri;
p.PropertyClass = PCl.Home;
p.PhoneType = Tel.Voice | Tel.BBS;
}
)
.Phones.SetIndexes()
.Addresses.Add(AddressBuilder
.Create()
.AddStreetName("Friedrichstraße")
.AddStreetNumber("22")
.AddLocality("Berlin")
.AddPostalCode("10117")
.AddCountry("Germany")
.Build(),
parameters: p =>
{
p.PropertyClass = PCl.Work;
p.AddressType = Adr.Dom | Adr.Intl | Adr.Postal | Adr.Parcel | Adr.Billing | Adr.Delivery;
p.TimeZone = TimeZoneID.TryCreate("Europe/Berlin");
p.GeoPosition = GeoCoordinate.TryCreate(52.51182050685474, 13.389581454284256, 10);
// Specifying the country or the ParameterSection.CountryCode property helps to format
// automatically appended address labels correctly:
p.CountryCode = "de-DE";
},
// Applying a group name to the AddressProperty helps to automatically preserve its Label,
// TimeZone and GeoCoordinate when writing a vCard 2.1 or vCard 3.0.
group: vc => vc.NewGroup()
)
// Append automatically formatted address labels:
.Addresses.AttachLabels(AddressFormatter.Default)
.EMails.Add("kaethe_mueller@internet.com", parameters: p => p.PropertyClass = PCl.Work)
.EMails.Add("mailto:kaethe_at_home@internet.com",
parameters: p =>
{
p.DataType = Data.Uri;
p.PropertyClass = PCl.Home;
}
)
.EMails.SetPreferences()
.Messengers.Add("https://wd.me/0123456789",
parameters: p => p.ServiceType = "WhatsDown")
.SocialMediaProfiles.Add("https://y.com/Semaphore",
parameters: p =>
{
p.UserName = "Semaphore";
p.ServiceType = "Y";
}
)
.BirthDayViews.Add(1984, 3, 28)
.Relations.Add("Paul Müller-Risinowsky",
Rel.Spouse | Rel.CoResident | Rel.Colleague
)
.AnniversaryViews.Add(2006, 7, 14)
.Notes.Add("Very experienced in Blazor.",
parameters: p =>
{
p.Created = DateTimeOffset.Now;
p.Author = new Uri("https://www.microsoft.com/");
p.AuthorName = "Satya Nadella";
}
)
.VCard;
}
void WriteResultsToConsole(VCard vcard)
{
WriteVCardToConsole(v2FileName, v2FilePath);
WriteVCardToConsole(v3FileName, v3FilePath);
WriteVCardToConsole(v4FileName, v4FilePath);
Console.WriteLine("Read VCard:");
Console.WriteLine();
Console.WriteLine(vcard);
static void WriteVCardToConsole(string fileName, string filePath)
{
Console.WriteLine($"{fileName}:");
Console.WriteLine(underLine);
Console.WriteLine(File.ReadAllText(filePath));
Console.WriteLine();
}
}
}
/// <summary>
/// Creates a small file, that simulates a photo.
/// </summary>
/// <param name="photoFilePath">Path to the created file.</param>
private static void CreatePhoto(string photoFilePath)
{
byte[] photo = new byte[60];
var rand = new Random();
rand.NextBytes(photo);
File.WriteAllBytes(photoFilePath, photo);
}
}
/*
Console Output:
VCard2.vcf:
----------
BEGIN:VCARD
VERSION:2.1
REV:2025-01-26T16:11:51Z
UID:0194a362-3947-7e93-8e1e-ff957b66a210
0.FN;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8;LANGUAGE=de-DE:Prof. Dr. K=C3=
=A4the Alexandra Caroline M=C3=BCller-Risinowsky II.
0.N;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8;LANGUAGE=de-DE:M=C3=BCller-Ris=
inowsky;K=C3=A4the;Alexandra Caroline;Prof. Dr.;II.
X-GENDER:Female
TITLE:CEO
ORG:Millers Company;C#;Webdesign
BDAY:1984-03-28
X-ANNIVERSARY:2006-07-14
1.ADR;DOM;INTL;POSTAL;PARCEL;WORK;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:=
;;Friedrichstra=C3=9Fe 22;Berlin;;10117;Germany
1.LABEL;DOM;INTL;POSTAL;PARCEL;WORK;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:=
Friedrichstra=C3=9Fe 22=0D=0A10117 Berlin=0D=0AGermany
1.GEO:52.511821;13.389581
1.TZ:+01:00
TEL;WORK;VOICE;MSG;CELL;BBS:tel:+49-321-1234567
TEL;HOME;VOICE;BBS:tel:+49-123-9876543
EMAIL;PREF;INTERNET:kaethe_mueller@internet.com
EMAIL;INTERNET:mailto:kaethe_at_home@internet.com
X-SOCIALPROFILE;X-SERVICE-TYPE=Y:https://y.com/Semaphore
X-SPOUSE;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:Paul M=C3=BCller-Risinows=
ky
NOTE:Very experienced in Blazor.
PHOTO;ENCODING=BASE64;TYPE=JPEG:
1/UOSmRuK0q3AsxVwEV4yE/EmKf2nbUM3+onTUXD4qGmEmBcUdkC2dlS72GgvwN+ZKc3HSGA8D
codQOW
END:VCARD
VCard3.vcf:
----------
BEGIN:VCARD
VERSION:3.0
REV:2025-01-26T16:11:51Z
UID:0194a362-3947-7e93-8e1e-ff957b66a210
0.FN;LANGUAGE=de-DE:Prof. Dr. Käthe Alexandra Caroline Müller-Risinowsky
II.
0.N;LANGUAGE=de-DE:Müller-Risinowsky;Käthe;Alexandra Caroline;Prof. Dr.;I
I.
X-GENDER:Female
TITLE:CEO
ORG:Millers Company;C#;Webdesign
BDAY;VALUE=DATE:1984-03-28
X-ANNIVERSARY:2006-07-14
1.ADR;TYPE=WORK,DOM,INTL,POSTAL,PARCEL:;;Friedrichstraße 22;Berlin;;10117;
Germany
1.LABEL;TYPE=WORK,DOM,INTL,POSTAL,PARCEL:Friedrichstraße 22\n10117 Berlin\
nGermany
1.GEO:52.511821;13.389581
1.TZ:+01:00
TEL;TYPE=WORK,VOICE,MSG,CELL,BBS:tel:+49-321-1234567
TEL;TYPE=HOME,VOICE,BBS:tel:+49-123-9876543
EMAIL;TYPE=INTERNET,PREF:kaethe_mueller@internet.com
EMAIL;TYPE=INTERNET:mailto:kaethe_at_home@internet.com
X-SOCIALPROFILE;X-SERVICE-TYPE=Y:https://y.com/Semaphore
IMPP;X-SERVICE-TYPE=WhatsDown:https://wd.me/0123456789
X-SPOUSE:Paul Müller-Risinowsky
NOTE:Very experienced in Blazor.
PHOTO;ENCODING=b;TYPE=JPEG:1/UOSmRuK0q3AsxVwEV4yE/EmKf2nbUM3+onTUXD4qGmEmBc
UdkC2dlS72GgvwN+ZKc3HSGA8DcodQOW
END:VCARD
VCard4.vcf:
----------
BEGIN:VCARD
VERSION:4.0
CREATED;VALUE=TIMESTAMP:20250126T161150Z
REV:20250126T161151Z
UID:urn:uuid:0194a362-3947-7e93-8e1e-ff957b66a210
0.FN;DERIVED=TRUE;LANGUAGE=de-DE;PID=1.1:Prof. Dr. Käthe Alexandra Carolin
e Müller-Risinowsky II.
0.N;LANGUAGE=de-DE;PID=1.1:Müller-Risinowsky;Käthe;Alexandra,Caroline;Pro
f.,Dr.;II.;;II.
GENDER;PID=1.1:F
TITLE;PID=1.1:CEO
ORG;PID=1.1:Millers Company;C#;Webdesign
BDAY;VALUE=DATE;PID=1.1:19840328
ANNIVERSARY;VALUE=DATE;PID=1.1:20060714
1.ADR;TYPE=WORK,billing,delivery;LABEL=Friedrichstraße 22\n10117 Berlin\nG
ermany;GEO="geo:52.511821,13.389581;u=10";TZ=Europe/Berlin;PID=1.1;CC=de-D
E:;;Friedrichstraße,22;Berlin;;10117;Germany;;;;22;Friedrichstraße;;;;;;
TEL;TYPE=WORK,VOICE,CELL,TEXT;VALUE=URI;PID=1.1;INDEX=1:tel:+49-321-1234567
TEL;TYPE=HOME,VOICE;VALUE=URI;PID=2.1;INDEX=2:tel:+49-123-9876543
EMAIL;TYPE=WORK;PREF=1;PID=1.1:kaethe_mueller@internet.com
EMAIL;TYPE=HOME;PREF=2;VALUE=URI;PID=2.1:mailto:kaethe_at_home@internet.com
SOCIALPROFILE;SERVICE-TYPE=Y;USERNAME=Semaphore;PID=1.1:https://y.com/Semap
hore
IMPP;SERVICE-TYPE=WhatsDown;PID=1.1:https://wd.me/0123456789
RELATED;TYPE=colleague,co-resident,spouse;VALUE=TEXT;PID=1.1:Paul Müller-R
isinowsky
NOTE;PID=1.1;AUTHOR-NAME=Satya Nadella;AUTHOR="https://www.microsoft.com/";
CREATED=20250126T161151Z:Very experienced in Blazor.
PHOTO;PID=1.1:data:image/jpeg;base64,1/UOSmRuK0q3AsxVwEV4yE/EmKf2nbUM3+onTU
XD4qGmEmBcUdkC2dlS72GgvwN+ZKc3HSGA8DcodQOW
CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556
GRAMGENDER;LANGUAGE=de;PID=1.1:feminine
END:VCARD
Read VCard:
Version: 3.0
[DataType: TimeStamp]
Updated: 2025-01-26 16:11:51Z
ContactID: Guid: 0194a362-3947-7e93-8e1e-ff957b66a210
GenderViews: Female
Titles: CEO
Organizations:
Name: Millers Company
Units: C#; Webdesign
[DataType: Date]
BirthDayViews: DateOnly: 03/28/1984
AnniversaryViews: DateOnly: 07/14/2006
[PropertyClass: Work]
[PhoneType: Voice, Msg, Cell, BBS]
Phones: tel:+49-321-1234567
[PropertyClass: Home]
[PhoneType: Voice, BBS]
Phones: tel:+49-123-9876543
[EMailType: INTERNET]
[Preference: 1]
EMails: kaethe_mueller@internet.com
[EMailType: INTERNET]
EMails: mailto:kaethe_at_home@internet.com
[ServiceType: Y]
SocialMediaProfiles: https://y.com/Semaphore
[ServiceType: WhatsDown]
Messengers: https://wd.me/0123456789
[RelationType: Spouse]
[DataType: Text]
Relations: String: Paul Müller-Risinowsky
Notes: Very experienced in Blazor.
[Encoding: Base64]
[MediaType: image/jpeg]
Photos: Byte[]: 60 Bytes
[Language: de-DE]
[Group: 0]
DisplayNames: Prof. Dr. Käthe Alexandra Caroline Müller-Risinowsky II.
[Language: de-DE]
[Group: 0]
NameViews:
Surnames: Müller-Risinowsky
Given: Käthe
Given2: Alexandra Caroline
Prefixes: Prof. Dr.
Suffixes: II.
[Group: 1]
TimeZones: +01:00
[Group: 1]
GeoCoordinates:
Latitude: 52.511821
Longitude: 13.389581
[PropertyClass: Work]
[AddressType: Dom, Intl, Postal, Parcel]
[Label:
Friedrichstraße 22
10117 Berlin
Germany]
[GeoPosition:
Latitude: 52.511821
Longitude: 13.389581]
[TimeZone: +01:00]
[Group: 1]
Addresses:
Street: Friedrichstraße 22
Locality: Berlin
PostalCode: 10117
Country: Germany
*/Properties
| ABLabels | X-ABLabel: An Apple AddressBook (AB) extension to give other vCard properties a label. |
| Access | CLASS: Describes the sensitivity of the information in the VCard. (3) |
| Addresses | ADR: A structured representation of the physical delivery address for the vCard object. (2,3,4) |
| AnniversaryViews | ANNIVERSARY: Defines the person's anniversary. (4) |
| BirthDayViews | BDAY: Date of birth of the individual associated with the vCard. (2,3,4) |
| BirthPlaceViews | BIRTHPLACE: The location of the individual's birth. (4 - RFC 6474) |
| CalendarAccessUris | CAPURI: A protocol independent location from which a calendaring and scheduling client can communicate with a user's entire calendar. (3 - RFC 2739) |
| CalendarAddresses | CALURI: URLs to the person's calendar. (4, 3 - RFC 2739) |
| CalendarUserAddresses | CALADRURI: URLs to use for sending a scheduling request to the person's calendar. (4, 3 - RFC 2739) |
| Categories | CATEGORIES: Lists of "tags" that can be used to describe the object represented by this vCard. (3,4) |
| ContactID | UID: Specifies a value that represents a persistent, globally unique identifier corresponding to the entity associated with the vCard. (2,3,4) |
| ContactUris | CONTACT-URI URIs representing an email address or a location for a web form.(4 - RFC 8605) |
| Created | CREATED: Defines the date and time when the vCard was created. (4 - RFC 9554) |
| DeathDateViews | DEATHDATE: The individual's time of death. (4 - RFC 6474) |
| DeathPlaceViews | DEATHPLACE: The location of the individual's death. (4 - RFC 6474) |
| DirectoryName | NAME: Provides a textual representation of the Sources property. (3) |
| DisplayNames | FN: The formatted name string associated with the vCard object. (2,3,4) |
| EMails | EMAIL: The addresses for electronic mail communication with the vCard object. (2,3,4) |
| Expertises | EXPERTISE: A professional subject area that the person has knowledge of. (RFC 6715) |
| FreeOrBusyUrls | FBURL: Defines URLs that show when the person is "free" or "busy" on their calendar. (4, 3 - RFC 2739) |
| GenderViews | GENDER: Defines the person's gender. (4) |
| GeoCoordinates | GEO: Specifies latitudes and longitudes. (2,3,4) |
| GramGenders | GRAMGENDER: Defines which grammatical gender to use in salutations and other grammatical constructs. 4 - RFC 9554 |
| Hobbies | HOBBY: Recreational activities that the person actively engages in. (4 - RFC 6715) |
| Interests | INTEREST: Recreational activities that the person is interested in, but does not necessarily take part in. (4 - RFC 6715) |
| JSContactProps | JSPROP: JSContact properties that cannot be converted to standardized vCard properties. (4 - RFC 9554) |
| Keys | KEY: Public encryption keys associated with the vCard object. (2,3,4) |
| Kind | KIND: Defines the type of entity, that this vCard represents. (4) |
| Language | LANGUAGE: Defines the default language that human-readable text values in this vCard are assumed to be written in. (4 - RFC 9554) |
| Logos | LOGO: Images or graphics of the logo of the organization that is associated with the individual to which the VCard belongs. (2,3,4) |
| Mailer | MAILER: Name of the e-mail program. (2,3) |
| Members | MEMBER: Defines a member that is part of the group that this VCard represents. The Kind property must be set to Group in order to use this property. (4) |
| Messengers | IMPP: Instant messenger handles. (3,4) |
| NameViews | N: A structured representation of the name of the person, place or thing associated with the vCard object. (2,3,4) |
| NickNames | NICKNAME: One or more descriptive/familiar names for the object represented by this vCard. (3,4) |
| NonStandards | vCard-Properties that don't belong to the standard. |
| Notes | NOTE: Specifies supplemental informations or comments that are associated with the vCard. (2,3,4) |
| Organizations | ORG: The name and optionally the unit(s) of the organization associated with the vCard object. (2,3,4) |
| OrgDirectories | ORG-DIRECTORY: A URI representing the person's work place, which can be used to look up information on the person's co-workers. (RFC 6715) |
| Phones | TEL: Canonical number strings for a telephone numbers for telephony communication with the vCard object. (2,3,4) |
| Photos | PHOTO: Image(s) or photograph(s) of the individual associated with the vCard. (2,3,4) |
| ProductID | PRODID: The identifier for the product that created the vCard object. (3,4) |
| Profile | PROFILE: States that the VCard is a vCard. (3) |
| Pronouns | PRONOUNS: Defines the pronouns that shall be used to refer to the entity represented by this VCard. (4 - RFC 9554) |
| Relations | RELATED: Other entities that the person or organization is related to. (4) |
| Roles | ROLE: The role, occupation, or business category of the vCard object within an organization. (2,3,4) |
| SocialMediaProfiles | SOCIALPROFILE: Specifies the URI or username for social media profiles associated with the object the VCard represents. (4 - RFC 9554) |
| Sounds | SOUND: Specifies the pronunciation of the DisplayNames property of the VCard-object. (2,3,4) |
| Sources | SOURCE: URLs that can be used to get the latest version of this vCard. (3,4) |
| SpokenLanguages | LANG: Defines languages that the person speaks. (4) |
| TimeZones | TZ: The time zone(s) of the vCard object. (2,3,4) |
| Titles | TITLE: Specifies the job title, functional position or function of the individual, associated with the vCard object, within an organization. (2,3,4) |
| Updated | REV: A time stamp for the last time the vCard was updated. (2,3,4) |
| Urls | URL: URLs, pointing to websites that represent the person in some way. (2,3,4) |
| VCard | Gets the VCard instance the VCardBuilder works with. |
| Xmls | XML: Any XML data that is attached to the vCard. (4) |
Methods
| Create(VCard) | Returns a VCardBuilder that edits the VCard object that is passed to the method as argument. |
| Create(Boolean, Boolean) | Returns a VCardBuilder that creates a new VCard object. |
| Equals | Determines whether the specified object is equal to the current object. (Inherited from Object) |
| GetHashCode | Serves as the default hash function. (Inherited from Object) |
| GetType | Gets the Type of the current instance. (Inherited from Object) |
| ToString | Returns a string that represents the current object. (Inherited from Object) |