Lavorare con file vCard (VCF) in C#

Questo articolo copre il VCardContact classe dal Aspose.Email.PersonalInfo.VCard namespace, che legge e scrive file vCard (VCF) indipendentemente da Outlook e MAPI. Per creare e gestire Outlook MapiContact elementi — che possono anche essere esportati verso VCF — vedi Gestione contatti Outlook.

VCardContact vs MapiContact

Aspose.Email espone i contatti tramite due classi diverse, e scegliere quella giusta evita molta confusione:

VCardContact (namespace Aspose.Email.PersonalInfo.VCard) — un oggetto vCard puro. Usalo quando la tua sorgente e destinazione sono file vCard (VCF) e non ti servono funzioni Outlook/MAPI. Legge e scrive VCF direttamente, supporta vCard 2.1/3.0/4.0, più contatti per file e caricamento asincrono.
MapiContact (namespace Aspose.Email.Mapi) — un contatto Outlook. Usalo quando lavori con MSG/PST o hai bisogno di proprietà specifiche MAPI. MapiContact può anche importare da e esportare verso VCF tramite il suo FromVCard e Save metodi (vedi Gestione contatti Outlook).

Il resto di questo articolo si concentra su VCardContact.

Crea una vCard e salvala

Il VCardContact la classe ha un costruttore senza parametri ed espone set di proprietà tipizzati come Informazioni di identificazione, Organizzazione, Email, TelephoneNumbers, e DeliveryAddresses.

Il seguente frammento di codice mostra come creare un contatto da zero e salvarlo come file 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 = "BerthaABuell@example.com",
            EmailType = VCardEmailType.INTERNET
        }
    }
};

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

Il modello delle proprietà del contatto

Oltre al nome e all’email mostrati sopra, un VCardContact espone l’intero modello di dati vCard tramite set di proprietà tipizzati. I frammenti qui sotto estendono il contact creati in precedenza. Ogni collezione può essere assegnata con un inizializzatore di collezione o ampliata con Add.

Indirizzi postali

Gli indirizzi postali vivono nella DeliveryAddresses collezione come VCardDeliveryAddress elementi. Il AddressType la proprietà accetta una combinazione di VCardDeliveryAddressType flag (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"
    }
};

Numeri di telefono

I numeri di telefono vivono nella TelephoneNumbers collezione come VCardTelephoneNumber elementi. Il TelephoneType la proprietà accetta una combinazione di VCardTelephoneType flag (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, e altro).

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

Posizione geografica

Il Geo la proprietà memorizza una posizione globale come float latitudine e longitudine.

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

Foto

Una foto del contatto è impostata su IdentificationInfo.Photo come un VCardPhoto. Può essere incorporata inline da byte di immagine o referenziata tramite URL. Il formato dell’immagine è dato da VCardPhotoType e la modalità di memorizzazione da 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
};

Etichette di indirizzo formattate

Un’etichetta è il testo formattato, pronto per la stampa, di un indirizzo di consegna. Le etichette vivono in Etichette collezione come VCardLabel elementi, ognuno etichettato con un tipo di indirizzo.

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

Leggi il modello di nuovo

Dopo aver caricato una vCard, gli stessi set di proprietà espongono i dati analizzati.

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

Sicurezza (Chiave pubblica o certificato)

Il Sicurezza proprietà espone la chiave pubblica o il certificato di autenticazione memorizzato nella vCard (il KEY proprietà). La sua SaveToPEM il metodo scrive quella chiave in un file 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");
}

Carica una vCard

Usa il metodo statico VCardContact.Load metodo per leggere una vCard da un file o da uno stream. Una volta caricati, le proprietà del contatto sono disponibili tramite gli stessi set di proprietà usati durante la creazione.

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

Carica con una codifica specifica

Per controllare la codifica del testo usata durante la lettura, passa un VCardLoadOptions oggetto con il suo PreferredEncoding imposta proprietà.

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

Leggi più contatti da un singolo file

Un file vCard può contenere più di un contatto. Usa il metodo statico IsMultiContacts metodo per controllare se un file o stream contiene più contatti, e LoadAsMultiple per leggerli tutti in un List<VCardContact>. Entrambi i metodi hanno overload per file, stream e opzioni di caricamento:

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

Carica contatti in modo asincrono

Per elenchi di contatti di grandi dimensioni o applicazioni I/O-bound (desktop, web o mobile), VCardContact fornisce il caricamento asincrono che non blocca il thread chiamante. Usa LoadAsync per un singolo contatto e LoadAsMultipleAsync per diversi casi. Entrambi accettano 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);
}

Opzioni di salvataggio

Il VCardSaveOptions la classe personalizza come viene scritto un contatto:

Versione — la versione vCard di output dal VCardVersion enumerazione: V21 (vCard 2.1, il predefinito), V30 (3.0), o V40 (4.0).
PreferredTextEncoding — la codifica usata quando si scrive il file.
UseExtensions — se esteso (X-) le proprietà possono essere scritte. Il valore predefinito è true.
ProductId — il valore scritto nel PRODID proprietà.

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

Vedi anche

Gestione contatti Outlook — crea, salva e legge Outlook MapiContact elementi, inclusa l’importazione ed esportazione VCF.
Gestione dei contatti nei file PST — memorizza e legge i contatti all’interno di un PST.

Lavorare con elementi Outlook Lavorare con file di storage Outlook