Travailler avec les fichiers vCard (VCF) en C#

Cet article couvre le VCardContact classe depuis le Aspose.Email.PersonalInfo.VCard espace de noms, qui lit et écrit les fichiers vCard (VCF) indépendamment d’Outlook et de MAPI. Pour créer et gérer Outlook MapiContact éléments — qui peuvent également être exportés vers VCF — voir Gestion des contacts Outlook.

VCardContact vs MapiContact

Aspose.Email expose les contacts via deux classes différentes, et choisir la bonne évite beaucoup de confusion :

• VCardContact (espace de noms Aspose.Email.PersonalInfo.VCard) — un objet vCard pur. Utilisez‑le lorsque votre source et votre destination sont des fichiers vCard (VCF) et que vous n’avez pas besoin des fonctionnalités Outlook/MAPI. Il lit et écrit le VCF directement, prend en charge vCard 2.1/3.0/4.0, plusieurs contacts par fichier et le chargement asynchrone.
• MapiContact (espace de noms Aspose.Email.Mapi) — un contact Outlook. Utilisez‑le lorsque vous travaillez avec MSG/PST ou avez besoin de propriétés spécifiques à MAPI. MapiContact peut également importer et exporter vers VCF via son FromVCard et Save méthodes (voir Gestion des contacts Outlook).

Le reste de cet article porte sur VCardContact.

Créer un vCard et l’enregistrer

Le VCardContact la classe possède un constructeur sans paramètre et expose des jeux de propriétés fortement typés tels que Informations d’identification, Organisation, E‑mails, TelephoneNumbers, et DeliveryAddresses.

Le fragment de code suivant montre comment créer un contact à partir de zéro et l’enregistrer en tant que fichier vCard (VCF).

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 = "[e-mail]",
            EmailType = VCardEmailType.INTERNET
        }
    }
};

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

Le modèle de propriétés du contact

Au-delà du nom et de l’e‑mail affichés ci‑dessus, un VCardContact expose le modèle de données complet du vCard via des jeux de propriétés fortement typés. Les extraits ci‑dessous étendent le contact créées précédemment. Chaque collection peut être initialisée avec un initialiseur de collection ou agrégée avec Add.

Adresses postales

Les adresses postales se trouvent dans le DeliveryAddresses collection en tant que VCardDeliveryAddress éléments. Le AddressType propriété accepte une combinaison de VCardDeliveryAddressType indicateurs (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"
    }
};

Numéros de téléphone

Les numéros de téléphone se trouvent dans le TelephoneNumbers collection en tant que VCardTelephoneNumber éléments. Le TelephoneType propriété accepte une combinaison de VCardTelephoneType indicateurs (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, et plus).

contact.TelephoneNumbers = new VCardTelephoneNumberCollection
{
    new VCardTelephoneNumber
    {
        TelephoneNumber = "[phone]",
        TelephoneType = VCardTelephoneType.WORK | VCardTelephoneType.VOICE
    },
    new VCardTelephoneNumber
    {
        TelephoneNumber = "[phone]",
        TelephoneType = VCardTelephoneType.CELL
    }
};

Position géographique

Le Geo propriété stocke une position globale comme float latitude et longitude.

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

Photo

Une photo de contact est définie sur IdentificationInfo.Photo en tant que VCardPhoto. Il peut être incorporé en ligne à partir d’octets d’image ou référencé par URL. Le format de l’image est indiqué par VCardPhotoType et le mode de stockage par 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
};

Étiquettes d’adresse formatées

Un label est le texte formaté, prêt à imprimer, d’une adresse de livraison. Les labels se trouvent dans le Labels collection en tant que VCardLabel éléments, chacun étiqueté avec un type d’adresse.

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

Lire le modèle à nouveau

Après avoir chargé un vCard, les mêmes jeux de propriétés exposent les données analysées.

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

Sécurité (clé publique ou certificat)

Le Sécurité propriété expose la clé publique ou le certificat d’authentification stocké dans le vCard (le KEY propriété). Son SaveToPEM méthode écrit cette clé dans un fichier PEM.

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

Charger un vCard

Utilisez la méthode statique VCardContact.Load méthode pour lire un vCard depuis un fichier ou un flux. Une fois chargé, les propriétés du contact sont accessibles via les mêmes jeux de propriétés utilisés lors de sa création.

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

Charger avec un encodage spécifique

Pour contrôler l’encodage du texte utilisé lors de la lecture, passez un VCardLoadOptions objet avec son PreferredEncoding propriété set.

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

Lire plusieurs contacts à partir d’un même fichier

Un fichier vCard peut contenir plusieurs contacts. Utilisez la méthode statique IsMultiContacts méthode pour vérifier si un fichier ou un flux contient plusieurs contacts, et LoadAsMultiple pour les lire tous dans un List<VCardContact>. Les deux méthodes offrent des surcharges fichier, flux et options de chargement :

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

Charger les contacts de façon asynchrone

Pour les grandes listes de contacts ou les applications I/O‑bound (bureau, web ou mobile), VCardContact fournit un chargement asynchrone qui ne bloque pas le thread appelant. Utilisez LoadAsync pour un contact unique et LoadAsMultipleAsync pour plusieurs. Les deux acceptent un 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);
}

Options d’enregistrement

Le VCardSaveOptions la classe personnalise la façon dont un contact est écrit :

• Version — la version vCard de sortie provenant du VCardVersion énumération : V21 (vCard 2.1, par défaut), V30 (3.0), ou V40 (4.0).
• PreferredTextEncoding — l’encodage utilisé lors de l’écriture du fichier.
• UseExtensions — si étendu (X-) les propriétés peuvent être écrites. La valeur par défaut est true.
• ProductId — la valeur écrite dans le PRODID propriété.

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

Voir aussi

• Gestion des contacts Outlook — créer, enregistrer et lire Outlook MapiContact éléments, y compris l’importation et l’exportation VCF.
• Gestion des contacts dans les fichiers PST — stocker et lire des contacts dans un PST.