Работа с vCard (VCF) файлове в C#

Тази статия обхваща VCardContact клас от Aspose.Email.PersonalInfo.VCard пространство от имена, което чете и записва vCard (VCF) файлове независимо от Outlook и MAPI. За създаване и управление на Outlook MapiContact елементи — които също могат да се експортират в VCF — вижте Управление на контакти в Outlook.

VCardContact срещу MapiContact

Aspose.Email разкрива контакти чрез два различни класа, а избирайки правилния се избягва много объркване:

  • VCardContact (пространство от имена Aspose.Email.PersonalInfo.VCard) — чист vCard обект. Използвайте го, когато вашият източник и цел са vCard (VCF) файлове и не се нуждаете от Outlook/MAPI функции. Чете и записва VCF директно, поддържа vCard 2.1/3.0/4.0, множество контакти в файл и асинхронно зареждане.
  • MapiContact (пространство от имена Aspose.Email.Mapi) — Outlook контакт. Използвайте го, когато работите с MSG/PST или се нуждаете от свойства специфични за MAPI. MapiContact може също да импортира и експортира VCF чрез своя FromVCard и Save методи (виж Управление на контакти в Outlook).

Останалата част от тази статия се фокусира върху VCardContact.

Създаване на vCard и запазване

Този VCardContact класът има конструктор без параметри и разкрива силно типизирани набори от свойства като IdentificationInfo, Organization, Emails, TelephoneNumbers, и DeliveryAddresses.

Следният кодов откъс показва как да създадете контакт от нула и да го запазите като 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");

Моделът на свойствата на контакта

В допълнение към името и имейла, показани по-горе, a VCardContact излага целия vCard модел на данни чрез силно типизирани набори от свойства. Примерите по-долу разширяват contact създадени по-рано. Всяка колекция може да бъде зададена с инициализатор на колекция или добавена със Add.

Пощенски адреси

Пощенските адреси се намират в DeliveryAddresses колекция като VCardDeliveryAddress елементи. The AddressType property приема комбинация от VCardDeliveryAddressType флагове (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"
    }
};

Телефонни номера

Телефонни номера се намират в TelephoneNumbers колекция като VCardTelephoneNumber елементи. The TelephoneType property приема комбинация от VCardTelephoneType флагове (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, и др.).

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

Географска позиция

Този Geo property съхранява глобална позиция като float ширина и дължина.

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

Снимка

Снимка на контакт се задава на IdentificationInfo.Photo като VCardPhoto. Той може да бъде вграден в реда от байтове на изображението или да се отнася чрез URL. Форматът на изображението се задава от VCardPhotoType и режимът на съхранение чрез 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
};

Форматирани адресни етикети

Етикетът е форматираният, готов за печат текст на адрес за доставка. Етикетите живеят в Labels колекция като VCardLabel елементи, всеки етикетиран с тип адрес.

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

Прочитане на модела обратно

След зареждане на vCard същите набори от свойства разкриват парсираните данни.

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

Сигурност (Публичен ключ или сертификат)

Този Security property разкрива публичния ключ или сертификата за удостоверяване, съхранени във vCard (този KEY property). Неговият SaveToPEM метод записва този ключ в 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");
}

Зареждане на vCard

Използвайте статичния VCardContact.Load метод за четене на vCard от файл или поток. След зареждане свойствата на контакта са достъпни чрез същите набори от свойства, използвани при създаването му.

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

Зареждане със специфично кодиране

За контролиране на текстовото кодиране, използвано при четене, предайте VCardLoadOptions обект с неговото PreferredEncoding набор свойства.

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

Четене на множество контакти от един файл

vCard файл може да съдържа повече от един контакт. Използвайте статичния IsMultiContacts метод за проверка дали файл или поток съдържат множество контакти и LoadAsMultiple за прочитане на всички в List<VCardContact>. И двата метода имат претоварени варианти за файл, поток и опции за зареждане:

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

Зареждане на контакти асинхронно

За големи списъци с контакти или I/O-обвързани приложения (десктоп, уеб или мобилни), VCardContact осигурява асинхронно зареждане, което не блокира извикващия поток. Използвайте LoadAsync за един контакт и LoadAsMultipleAsync за няколко. И двете приемат 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);
}

Опции за запазване

Този VCardSaveOptions класът персонализира как се записва контакт:

  • Version — изходната версия на vCard от VCardVersion енумерация: V21 (vCard 2.1, по подразбиране), V30 (3.0), или V40 (4.0).
  • PreferredTextEncoding — кодирането, използвано при записване на файла.
  • UseExtensions — дали е разширен (X-) свойства могат да бъдат записани. По подразбиране е true.
  • ProductId — стойността записана в PRODID свойство.
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);

Виж също

Работа с Outlook елементи Работа с Outlook файлове за хранилище