Работа с файлами vCard (VCF) на C#

Эта статья охватывает VCardContact классом из Aspose.Email.PersonalInfo.VCard пространство имён, которое читает и пишет файлы vCard (VCF) независимо от Outlook и MAPI. Чтобы создавать и управлять Outlook MapiContact элементы — которые также могут быть экспортированы в VCF — см. Управление контактами Outlook.

VCardContact vs 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, Организация, Электронные письма, TelephoneNumbers, and 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");

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

Помимо имени и электронной почты, показанных выше, VCardContact открывает полную модель данных vCard через типобезопасные наборы свойств. Приведённые ниже фрагменты кода расширяют contact созданных ранее. Каждую коллекцию можно инициализировать с помощью инициализатора коллекции или добавить к ней через Add.

Почтовые адреса

Почтовые адреса находятся в DeliveryAddresses коллекцию как VCardDeliveryAddress элементов. Свойство 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 элементов. Свойство 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