Werken met vCard (VCF)-bestanden in C#

Dit artikel behandelt de VCardContact klasse van de Aspose.Email.PersonalInfo.VCard naamruimte, die vCard (VCF)-bestanden onafhankelijk van Outlook en MAPI leest en schrijft. Om Outlook MapiContact items — die ook kunnen worden geëxporteerd naar VCF — zie Beheer van Outlook‑contactpersonen.

VCardContact versus MapiContact

Aspose.Email biedt contacten via twee verschillende klassen, en de juiste kiezen voorkomt veel verwarring:

  • VCardContact (naamruimte Aspose.Email.PersonalInfo.VCard) — een puur vCard‑object. Gebruik deze wanneer je bron- en doelbestanden vCard (VCF) zijn en je geen Outlook/MAPI‑functies nodig hebt. Het leest en schrijft VCF direct, ondersteunt vCard 2.1/3.0/4.0, meerdere contacten per bestand en asynchroon laden.
  • MapiContact (naamruimte Aspose.Email.Mapi) — een Outlook‑contact. Gebruik deze wanneer je werkt met MSG/PST of MAPI‑specifieke eigenschappen nodig hebt. MapiContact kan ook importeren uit en exporteren naar VCF via zijn FromVCard en Save methoden (zie Beheer van Outlook‑contactpersonen).

De rest van dit artikel richt zich op VCardContact.

Maak een vCard en sla deze op

De VCardContact klasse heeft een parameterloze constructor en biedt sterk getypeerde eigenschapsets zoals IdentificatieInfo, Organisatie, E‑mails, TelephoneNumbers, and DeliveryAddresses.

De volgende code‑snippet laat zien hoe je een contact vanaf nul bouwt en opslaat als een vCard (VCF)-bestand.

using Aspose.Email.PersonalInfo.VCard;

var contact = new VCardContact
{
    IdentificationInfo = new VCardIdentificationInfo
    {
        DisplayName = "Bertha Buell",
        FullName = "Bertha A. Buell",
        Nickname = "Bertie",
        Birthday = new DateTime(1980, 5, 20)
    },
    Organization = new VCardOrganization
    {
        Organization = "Awthentikz",
        Title = "Social work assistant"
    },
    Emails = new VCardEmailCollection
    {
        new VCardEmail
        {
            EmailAddress = "BerthaABuell@example.com",
            EmailType = VCardEmailType.INTERNET
        }
    }
};

// Save as a vCard (VCF) file
contact.Save("contact.vcf");

Het contact‑eigenschapsmodel

Naast de naam en e‑mail die hierboven worden getoond, een VCardContact maakt het volledige vCard‑datamodel toegankelijk via sterk getypeerde eigenschapsets. De onderstaande fragmenten breiden de contact gecreëerd eerder. Elke collectie kan worden toegewezen met een collectie‑initializer of aangevuld met Add.

Postadressen

Postadressen staan in de DeliveryAddresses collectie als VCardDeliveryAddress items. De AddressType eigenschap neemt een combinatie van VCardDeliveryAddressType vlaggen (HOME, WORK, POSTAL, PARCEL, DOM, INTL, PREF).

contact.DeliveryAddresses = new VCardDeliveryAddressCollection
{
    new VCardDeliveryAddress
    {
        AddressType = VCardDeliveryAddressType.WORK | VCardDeliveryAddressType.PREF,
        Street = "4 Darwinia Loop",
        Locality = "Eighty Mile Beach",
        Region = "WA",
        PostalCode = "6725",
        CountryName = "Australia"
    }
};

Telefoonnummers

Telefoonnummers staan in de TelephoneNumbers collectie als VCardTelephoneNumber items. De TelephoneType eigenschap neemt een combinatie van VCardTelephoneType vlaggen (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, en meer).

contact.TelephoneNumbers = new VCardTelephoneNumberCollection
{
    new VCardTelephoneNumber
    {
        TelephoneNumber = "(08) 9080 1183",
        TelephoneType = VCardTelephoneType.WORK | VCardTelephoneType.VOICE
    },
    new VCardTelephoneNumber
    {
        TelephoneNumber = "(925) 599 3355",
        TelephoneType = VCardTelephoneType.CELL
    }
};

Geografische positie

De Geo eigenschap slaat een wereldpositie op als float breedte- en lengtegraad.

contact.Geo = new VCardGeo
{
    Latitude = 48.858844f,
    Longitude = 2.294351f
};

Foto

Een contactfoto wordt ingesteld op IdentificationInfo.Photo als een VCardPhoto. Het kan inline worden ingebed vanuit afbeeldingsbytes of worden verwezen via een URL. Het afbeeldingformaat wordt gegeven door VCardPhotoType en de opslagmodus door VCardValueLocation.

// Embed the image bytes inline
contact.IdentificationInfo.Photo = new VCardPhoto
{
    Data = File.ReadAllBytes("portrait.jpg"),
    PhotoType = VCardPhotoType.JPEG,
    ValueLocation = VCardValueLocation.INLINE
};

// Or reference an external image by URL
contact.IdentificationInfo.Photo = new VCardPhoto
{
    Uri = "https://example.com/portrait.jpg",
    PhotoType = VCardPhotoType.JPEG,
    ValueLocation = VCardValueLocation.URL
};

Geformatteerde adreslabels

Een label is de opgemaakte, afdrukklare tekst van een afleveradres. Labels staan in de Labels collectie als VCardLabel items, elk gemarkeerd met een adresstype.

contact.Labels = new VCardLabelCollection
{
    new VCardLabel
    {
        AddressType = VCardDeliveryAddressType.WORK,
        Address = "4 Darwinia Loop\r\nEighty Mile Beach WA 6725\r\nAustralia"
    }
};

Lees het model terug

Na het laden van een vCard, geven dezelfde eigenschapsets de geparseerde gegevens weer.

var loaded = VCardContact.Load("contact.vcf");

Console.WriteLine(loaded.IdentificationInfo?.DisplayName);

foreach (var address in loaded.DeliveryAddresses)
{
    Console.WriteLine($"{address.AddressType}: {address.Street}, {address.Locality}");
}

foreach (var phone in loaded.TelephoneNumbers)
{
    Console.WriteLine($"{phone.TelephoneType}: {phone.TelephoneNumber}");
}

if (loaded.Geo != null)
{
    Console.WriteLine($"Geo: {loaded.Geo.Latitude}, {loaded.Geo.Longitude}");
}

Beveiliging (Openbare sleutel of certificaat)

De Beveiliging eigenschap geeft de openbare sleutel of het authenticatiecertificaat weer dat in de vCard is opgeslagen (de KEY eigenschap). De SaveToPEM methode schrijft die sleutel naar een PEM-bestand.

var signed = VCardContact.Load("signed.vcf");

if (signed.Security != null && signed.Security.Key != null)
{
    Console.WriteLine("Key type: " + signed.Security.Type);

    // Export the embedded public key / certificate to a PEM file
    signed.Security.SaveToPEM("public-key.pem");
}

Laad een vCard

Gebruik de statische VCardContact.Load methode om een vCard te lezen uit een bestand of een stream. Eenmaal geladen, zijn de eigenschappen van het contact via dezelfde eigenschapsets beschikbaar die bij het maken werden gebruikt.

// Load from a file
var contact = VCardContact.Load("contact.vcf");
Console.WriteLine(contact.IdentificationInfo.DisplayName);

// Load from a stream
using (var stream = File.OpenRead("contact.vcf"))
{
    var fromStream = VCardContact.Load(stream);
}

Laad met een specifieke codering

Om de tekencodering te regelen die wordt gebruikt bij het lezen, geef een VCardLoadOptions object met zijn PreferredEncoding eigenschapset.

var loadOptions = new VCardLoadOptions { PreferredEncoding = Encoding.UTF8 };
var contact = VCardContact.Load("contact.vcf", loadOptions);

Lees meerdere contacten uit één bestand

Een vCard-bestand kan meer dan één contact bevatten. Gebruik de statische IsMultiContacts methode om te controleren of een bestand of stream meerdere contacten bevat, en LoadAsMultiple om ze allemaal in een List<VCardContact>. Beide methoden hebben overloads voor bestand, stream en laadopties:

  • static bool IsMultiContacts(string filePath) / IsMultiContacts(Stream stream)
  • static List<VCardContact> LoadAsMultiple(string filePath) / LoadAsMultiple(string filePath, VCardLoadOptions options)
  • static List<VCardContact> LoadAsMultiple(Stream stream) / LoadAsMultiple(Stream stream, VCardLoadOptions options)
using (var stream = new FileStream("contacts.vcf", FileMode.Open, FileAccess.Read))
{
    if (VCardContact.IsMultiContacts(stream))
    {
        List<VCardContact> contacts = VCardContact.LoadAsMultiple(stream);

        foreach (var contact in contacts)
        {
            Console.WriteLine(contact.IdentificationInfo.DisplayName);
        }
    }
}

Laad contacten asynchroon

Voor grote contactenlijsten of I/O-gebonden toepassingen (desktop, web of mobiel), VCardContact biedt asynchroon laden dat de aanroepende thread niet blokkeert. Gebruik LoadAsync voor één contact en LoadAsMultipleAsync voor verschillende. Beide accepteren een CancellationToken.

// A single contact
var contact = await VCardContact.LoadAsync("contact.vcf", CancellationToken.None);
Console.WriteLine(contact.IdentificationInfo.DisplayName);

// Multiple contacts
var contacts = await VCardContact.LoadAsMultipleAsync(
    "contacts.vcf", new VCardLoadOptions(), CancellationToken.None);

foreach (var loaded in contacts)
{
    Console.WriteLine(loaded.IdentificationInfo.DisplayName);
}

Opslagopties

De VCardSaveOptions klasse aanpast hoe een contact wordt geschreven:

  • Versie — de uitgaande vCard-versie van de VCardVersion enumeratie: V21 (vCard 2.1, de standaard), V30 (3.0), of V40 (4.0).
  • PreferredTextEncoding — de codering die wordt gebruikt bij het schrijven van het bestand.
  • UseExtensions — of uitgebreid (X-) eigenschappen kunnen worden geschreven. Standaard is true.
  • ProductId — de waarde die geschreven wordt naar de PRODID eigenschap.
var contact = VCardContact.Load("contact.vcf");

var saveOptions = new VCardSaveOptions
{
    Version = VCardVersion.V30,             // write vCard 3.0 (default is V21)
    PreferredTextEncoding = Encoding.UTF8,  // encoding used when writing
    UseExtensions = true,                   // allow extended (X-) properties
    ProductId = "My Company"                // PRODID value
};

contact.Save("contact_v3.vcf", saveOptions);

Zie ook

Werken met Outlook‑items Werken met Outlook‑opslagbestanden