Trabajando con archivos vCard (VCF) en C#

Este artículo cubre el VCardContact clase desde el Aspose.Email.PersonalInfo.VCard espacio de nombres, que lee y escribe archivos vCard (VCF) independientemente de Outlook y MAPI. Para crear y gestionar Outlook MapiContact elementos — que también pueden exportarse a VCF — vea Gestión de Contactos de Outlook.

VCardContact vs MapiContact

Aspose.Email expone contactos a través de dos clases diferentes, y elegir la adecuada evita mucha confusión:

VCardContact (espacio de nombres Aspose.Email.PersonalInfo.VCard) — un objeto vCard puro. Úselo cuando su origen y destino sean archivos vCard (VCF) y no necesite funciones de Outlook/MAPI. Lee y escribe VCF directamente, soporta vCard 2.1/3.0/4.0, múltiples contactos por archivo y carga asíncrona.
MapiContact (espacio de nombres Aspose.Email.Mapi) — un contacto de Outlook. Úselo cuando trabaje con MSG/PST o necesite propiedades específicas de MAPI. MapiContact también puede importar y exportar VCF a través de su FromVCard y Save métodos (ver Gestión de Contactos de Outlook).

El resto de este artículo se centra en VCardContact.

Crear un vCard y guardarlo

El VCardContact la clase tiene un constructor sin parámetros y expone conjuntos de propiedades tipados fuertemente como Información de identificación, Organización, Correos electrónicos, TelephoneNumbers, y DeliveryAddresses.

El siguiente fragmento de código muestra cómo crear un contacto desde cero y guardarlo como un archivo 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");

El modelo de propiedad de contacto

Más allá del nombre y correo electrónico mostrados arriba, un VCardContact expone el modelo de datos completo de vCard a través de conjuntos de propiedades tipados fuertemente. Los fragmentos a continuación amplían el contact creado anteriormente. Cada colección puede asignarse con un inicializador de colección o ampliarse con Add.

Direcciones postales

Las direcciones postales viven en el DeliveryAddresses colección como VCardDeliveryAddress elementos. El AddressType propiedad acepta una combinación de VCardDeliveryAddressType banderas (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 teléfono

Los números de teléfono viven en el TelephoneNumbers colección como VCardTelephoneNumber elementos. El TelephoneType propiedad acepta una combinación de VCardTelephoneType banderas (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, y más).

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

Posición geográfica

El Geo propiedad almacena una posición global como float latitud y longitud.

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

Foto

Una foto de contacto se establece en IdentificationInfo.Photo como un VCardPhoto. Puede incrustarse en línea a partir de bytes de imagen o referenciarse mediante URL. El formato de imagen se indica por VCardPhotoType y el modo de almacenamiento 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
};

Etiquetas de dirección formateada

Una etiqueta es el texto formateado, listo para imprimir, de una dirección de entrega. Las etiquetas viven en el Etiquetas colección como VCardLabel elementos, cada uno etiquetado con un tipo de dirección.

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

Leer el modelo de nuevo

Después de cargar un vCard, los mismos conjuntos de propiedades exponen los datos analizados.

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

Seguridad (clave pública o certificado)

El Seguridad propiedad expone la clave pública o certificado de autenticación almacenado en el vCard (el KEY propiedad). Su SaveToPEM método escribe esa clave en un archivo 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");
}

Cargar un vCard

Use el estático VCardContact.Load método para leer un vCard desde un archivo o un flujo. Una vez cargado, las propiedades del contacto están disponibles a través de los mismos conjuntos de propiedades usados al crearlo.

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

Cargar con una codificación específica

Para controlar la codificación de texto usada al leer, pase un VCardLoadOptions objeto con su PreferredEncoding propiedad establecida.

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

Leer varios contactos de un solo archivo

Un archivo vCard puede contener más de un contacto. Use el método estático IsMultiContacts método para comprobar si un archivo o flujo contiene varios contactos, y LoadAsMultiple para leerlos todos en un List<VCardContact>. Ambos métodos tienen sobrecargas para archivo, flujo y opciones de carga:

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

Cargar contactos de forma asíncrona

Para listas de contactos grandes o aplicaciones con I/O intensivo (escritorio, web o móvil), VCardContact provee carga asíncrona que no bloquea el hilo llamador. Use LoadAsync para un solo contacto y LoadAsMultipleAsync para varios. Ambos aceptan 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);
}

Opciones de guardado

El VCardSaveOptions la clase personaliza cómo se escribe un contacto:

Version — la versión vCard de salida del VCardVersion enumeración: V21 (vCard 2.1, el predeterminado), V30 (3.0), o V40 (4.0).
PreferredTextEncoding — la codificación usada al escribir el archivo.
UseExtensions — si es extendido (X-) propiedades pueden ser escritas. El valor predeterminado es true.
ProductId — el valor escrito al PRODID propiedad.

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

Ver también

Gestión de Contactos de Outlook — crear, guardar y leer Outlook MapiContact elementos, incluyendo importación y exportación de VCF.
Administrar contactos en archivos PST — almacenar y leer contactos dentro de un PST.

Trabajando con elementos de Outlook Trabajando con archivos de almacenamiento Outlook