Arbeiten mit vCard (VCF)-Dateien in C#

Dieser Artikel behandelt die VCardContact Klasse aus dem Aspose.Email.PersonalInfo.VCard Namespace, das vCard‑(VCF‑)Dateien unabhängig von Outlook und MAPI liest und schreibt. Um Outlook zu erstellen und zu verwalten MapiContact Elemente — die ebenfalls zu VCF exportiert werden können — siehe Verwaltung von Outlook‑Kontakten.

VCardContact vs MapiContact

Aspose.Email stellt Kontakte über zwei verschiedene Klassen bereit, und die Wahl der richtigen verhindert viel Verwirrung:

VCardContact (Namespace Aspose.Email.PersonalInfo.VCard) — ein reines vCard‑Objekt. Verwenden Sie dies, wenn Quelle und Ziel vCard‑(VCF‑)Dateien sind und Sie keine Outlook/MAPI‑Funktionen benötigen. Es liest und schreibt VCF direkt, unterstützt vCard 2.1/3.0/4.0, mehrere Kontakte pro Datei und asynchrones Laden.
MapiContact (Namespace Aspose.Email.Mapi) — ein Outlook‑Kontakt. Verwenden Sie dies, wenn Sie mit MSG/PST arbeiten oder MAPI‑spezifische Eigenschaften benötigen. MapiContact kann außerdem von und zu VCF über seine FromVCard und Save Methoden (siehe Verwaltung von Outlook‑Kontakten).

Der Rest dieses Artikels konzentriert sich auf VCardContact.

Eine vCard erstellen und speichern

Die VCardContact Klasse hat einen parameterlosen Konstruktor und stellt stark typisierte Eigenschaftsmengen bereit, wie zum Beispiel Identifikationsinformationen, Organisation, E‑Mails, TelephoneNumbers, und DeliveryAddresses.

Der folgende Codeausschnitt zeigt, wie man einen Kontakt von Grund auf erstellt und als vCard (VCF)-Datei speichert.

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");

Das Kontakt‑Eigenschaftsmodell

Über den Namen und die oben gezeigte E‑Mail hinaus, ein VCardContact stellt das vollständige vCard-Datenmodell über stark typisierte Eigenschaftsmengen bereit. Die nachfolgenden Snippets erweitern das contact wie zuvor erstellt. Jede Sammlung kann mit einem Sammlungsinitialisierer zugewiesen oder mit Add.

Postadressen

Postadressen befinden sich im DeliveryAddresses Sammlung als VCardDeliveryAddress Elementen. Die AddressType Eigenschaft akzeptiert eine Kombination von VCardDeliveryAddressType Flags (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"
    }
};

Telefonnummern

Telefonnummern befinden sich im TelephoneNumbers Sammlung als VCardTelephoneNumber Elementen. Die TelephoneType Eigenschaft akzeptiert eine Kombination von VCardTelephoneType Flags (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, und mehr).

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 Position

Die Geo Eigenschaft speichert eine globale Position als float Breitengrad und Längengrad.

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

Foto

Ein Kontaktfoto wird gesetzt auf IdentificationInfo.Photo als ein VCardPhoto. Es kann inline aus Bildbytes eingebettet oder per URL referenziert werden. Das Bildformat wird angegeben durch VCardPhotoType und der Speicherungsmodus über 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
};

Formatierte Adressetiketten

Ein Label ist der formatierte, druckfertige Text einer Lieferadresse. Labels befinden sich im Labels Sammlung als VCardLabel Elemente, jeweils mit einem Adresstyp gekennzeichnet.

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

Das Modell wieder einlesen

Nach dem Laden einer vCard stellen dieselben Eigenschaftsmengen die geparsten Daten bereit.

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}");
}

Sicherheit (öffentlicher Schlüssel oder Zertifikat)

Die Sicherheit Eigenschaft gibt den öffentlichen Schlüssel oder das Authentifizierungszertifikat frei, das in der vCard gespeichert ist (das KEY Eigenschaft). Seine SaveToPEM Methode schreibt diesen Schlüssel in eine PEM-Datei.

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");
}

Eine vCard laden

Verwenden Sie die statische VCardContact.Load Methode, um eine vCard aus einer Datei oder einem Stream zu lesen. Sobald geladen, sind die Eigenschaften des Kontakts über dieselben Eigenschaftsmengen zugänglich, die beim Erstellen verwendet wurden.

// 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);
}

Laden mit einer spezifischen Kodierung

Um die beim Lesen verwendete Textkodierung zu steuern, übergeben Sie ein VCardLoadOptions Objekt mit seinem PreferredEncoding Eigenschaftsmenge.

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

Mehrere Kontakte aus einer einzelnen Datei lesen

Eine vCard-Datei kann mehr als einen Kontakt enthalten. Verwenden Sie die statische IsMultiContacts Methode, um zu prüfen, ob eine Datei oder ein Stream mehrere Kontakte enthält, und LoadAsMultiple um sie alle in ein List<VCardContact>. Beide Methoden haben Überladungen für Datei, Stream und Lademöglichkeiten:

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);
        }
    }
}

Kontakte asynchron laden

Für große Kontaktlisten oder I/O-lastige Anwendungen (Desktop, Web oder Mobilgeräte), VCardContact bietet asynchrones Laden, das den aufrufenden Thread nicht blockiert. Verwenden Sie LoadAsync für einen einzelnen Kontakt und LoadAsMultipleAsync für mehrere. Beide akzeptieren ein 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);
}

Speicheroptionen

Die VCardSaveOptions Klasse passt an, wie ein Kontakt geschrieben wird:

Version — die AusgabevCard-Version aus dem VCardVersion Aufzählung: V21 (vCard 2.1, Standard), V30 (3.0) oder V40 (4.0).
PreferredTextEncoding — die beim Schreiben der Datei verwendete Kodierung.
UseExtensions — ob erweitert (X-) Eigenschaften geschrieben werden kann. Standard ist true.
ProductId — der Wert, der in das PRODID Eigenschaft.

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);

Siehe auch

Verwaltung von Outlook‑Kontakten — Outlook erstellen, speichern und lesen MapiContact Elemente, einschließlich VCF-Import und -Export.
Verwalten von Kontakten in PST‑Dateien — Kontakte in einer PST speichern und lesen.

Arbeiten mit Outlook‑Elementen Arbeiten mit Outlook‑Speicherdateien