Trabalhando com Arquivos vCard (VCF) em C#

Este artigo cobre o VCardContact classe a partir do Aspose.Email.PersonalInfo.VCard namespace, que lê e grava arquivos vCard (VCF) independentemente do Outlook e MAPI. Para criar e gerenciar Outlook MapiContact itens — que também podem ser exportados para VCF — veja Gerenciamento de Contatos do Outlook.

VCardContact vs MapiContact

Aspose.Email expõe contatos por meio de duas classes diferentes, e escolher a correta evita muita confusão:

VCardContact (namespace Aspose.Email.PersonalInfo.VCard) — um objeto vCard puro. Use quando sua origem e destino são arquivos vCard (VCF) e não precisar de recursos do Outlook/MAPI. Ele lê e grava VCF diretamente, suporta vCard 2.1/3.0/4.0, múltiplos contatos por arquivo e carregamento assíncrono.
MapiContact (namespace Aspose.Email.Mapi) — um contato do Outlook. Use quando trabalhar com MSG/PST ou precisar de propriedades específicas do MAPI. MapiContact também pode importar e exportar VCF via seu FromVCard e Save métodos (veja Gerenciamento de Contatos do Outlook).

O resto deste artigo foca em VCardContact.

Criar um vCard e Salvá‑lo

O VCardContact classe tem um construtor sem parâmetros e expõe conjuntos de propriedades tipados como IdentificationInfo, Organização, Emails, TelephoneNumbers, e DeliveryAddresses.

O snippet de código a seguir mostra como criar um contato do zero e salvá‑lo como um arquivo 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");

O Modelo de Propriedades do Contato

Além do nome e e‑mail mostrados acima, um VCardContact exibe o modelo de dados completo do vCard através de conjuntos de propriedades tipados. Os trechos abaixo estendem o contact criados anteriormente. Cada coleção pode ser atribuída com um inicializador de coleção ou acrescentada com Add.

Endereços Postais

Endereços postais vivem em DeliveryAddresses coleção como VCardDeliveryAddress itens. O AddressType propriedade aceita uma combinação de 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"
    }
};

Números de Telefone

Números de telefone vivem em TelephoneNumbers coleção como VCardTelephoneNumber itens. O TelephoneType propriedade aceita uma combinação de VCardTelephoneType flags (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, e mais).

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

Posição Geográfica

O Geo propriedade armazena uma posição global como float latitude e longitude.

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

Foto

Uma foto de contato é definida em IdentificationInfo.Photo como um VCardPhoto. Pode ser incorporado inline a partir de bytes de imagem ou referenciado por URL. O formato da imagem é definido por VCardPhotoType e o modo de armazenamento por 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
};

Rótulos de Endereço Formatados

Um rótulo é o texto formatado, pronto para impressão, de um endereço de entrega. Os rótulos vivem em Labels coleção como VCardLabel itens, cada um marcado com um tipo de endereço.

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

Ler o Modelo de Volta

Após carregar um vCard, os mesmos conjuntos de propriedades expõem os dados analisados.

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

Segurança (Chave Pública ou Certificado)

O Segurança propriedade expõe a chave pública ou certificado de autenticação armazenado no vCard (o KEY propriedade). Seu SaveToPEM método grava essa chave em um arquivo 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");
}

Carregar um vCard

Use o método estático VCardContact.Load método para ler um vCard de um arquivo ou stream. Uma vez carregado, as propriedades do contato ficam disponíveis através dos mesmos conjuntos de propriedades usados ao criá-lo.

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

Carregar com uma Codificação Específica

Para controlar a codificação de texto usada ao ler, passe um VCardLoadOptions objeto com seu PreferredEncoding conjunto de propriedades.

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

Ler Múltiplos Contatos de um Único Arquivo

Um arquivo vCard pode conter mais de um contato. Use o método estático IsMultiContacts método para verificar se um arquivo ou stream contém múltiplos contatos, e LoadAsMultiple para lê-los todos em um List<VCardContact>. Ambos os métodos têm sobrecargas de arquivo, stream e opções de carregamento:

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

Carregar Contatos Assincronamente

Para listas de contatos grandes ou aplicativos I/O-bound (desktop, web ou mobile), VCardContact fornece carregamento assíncrono que não bloqueia a thread de chamada. Use LoadAsync para um único contato e LoadAsMultipleAsync para vários. Ambos aceitam um 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);
}

Opções de Salvar

O VCardSaveOptions classe personaliza como um contato é escrito:

Version — a versão de saída do vCard a partir do VCardVersion enumeração: V21 (vCard 2.1, o padrão), V30 (3.0), ou V40 (4.0).
PreferredTextEncoding — a codificação usada ao gravar o arquivo.
UseExtensions — se estendido (X-) propriedades podem ser escritas. O padrão é true.
ProductId — o valor escrito no PRODID propriedade.

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

Veja Também

Gerenciamento de Contatos do Outlook — criar, salvar e ler Outlook MapiContact itens, incluindo importação e exportação de VCF.
Gerenciando Contatos em Arquivos PST — armazenar e ler contatos dentro de um PST.

Trabalhando com Itens do Outlook Trabalhando com Arquivos de Armazenamento Outlook