Робота з файлами 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 і зберегти його

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

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

Окрім імені та електронної пошти, показаних вище, VCardContact надає повну модель даних vCard через строго типізовані набори властивостей. Наведені нижче фрагменти розширюють contact створені раніше. Кожну колекцію можна ініціалізувати за допомогою ініціалізатора колекції або доповнювати за допомогою Add.

Поштові адреси

Поштові адреси зберігаються у DeliveryAddresses колекція як VCardDeliveryAddress елементів. AddressType властивість приймає комбінацію 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 властивість приймає комбінацію 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
    }
};

Географічна позиція

The Geo властивість зберігає глобальну позицію як 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}");
}

Безпека (відкритий ключ або сертифікат)

The Security властивість надає відкритий ключ або сертифікат автентифікації, що зберігаються у vCard ( KEY властивість). Його 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);
}

Параметри збереження

The 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