Làm việc với tệp vCard (VCF) trong C#

Bài viết này bao gồm VCardContact lớp từ Aspose.Email.PersonalInfo.VCard namespace, đọc và ghi tệp vCard (VCF) độc lập với Outlook và MAPI. Để tạo và quản lý Outlook MapiContact các mục — có thể cũng được xuất sang VCF — xem Quản lý Danh bạ Outlook.

VCardContact vs MapiContact

Aspose.Email cung cấp danh bạ qua hai lớp khác nhau, và việc chọn đúng lớp sẽ tránh nhiều nhầm lẫn:

VCardContact (namespace Aspose.Email.PersonalInfo.VCard) — một đối tượng vCard thuần. Sử dụng khi nguồn và đích của bạn là các tệp vCard (VCF) và bạn không cần các tính năng Outlook/MAPI. Nó đọc và ghi VCF trực tiếp, hỗ trợ vCard 2.1/3.0/4.0, nhiều liên hệ mỗi tệp, và tải không đồng bộ.
MapiContact (namespace Aspose.Email.Mapi) — một liên hệ Outlook. Sử dụng nó khi bạn làm việc với MSG/PST hoặc cần các thuộc tính đặc thù MAPI. MapiContact cũng có thể nhập và xuất sang VCF qua FromVCard và Save phương thức (xem Quản lý Danh bạ Outlook).

Phần còn lại của bài viết này tập trung vào VCardContact.

Tạo một vCard và Lưu Nó

Cái VCardContact lớp có một constructor không tham số và tiết lộ các tập hợp thuộc tính kiểu mạnh như IdentificationInfo, Organization, Emails, TelephoneNumbers, và DeliveryAddresses.

Đoạn mã sau cho bạn thấy cách xây dựng một liên hệ từ đầu và lưu nó như một tệp 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");

Mô Hình Thuộc Tính Liên Hệ

Ngoài tên và email đã hiển thị ở trên, một VCardContact tiết lộ toàn bộ mô hình dữ liệu vCard thông qua các tập hợp thuộc tính kiểu mạnh. Các đoạn mã dưới mở rộng contact được tạo trước. Mỗi bộ sưu tập có thể được khởi tạo bằng một khởi tạo bộ sưu tập hoặc thêm vào bằng Add.

Địa Chỉ Bưu Điện

Địa chỉ bưu điện tồn tại trong DeliveryAddresses bộ sưu tập như VCardDeliveryAddress các mục. Các AddressType thuộc tính nhận một sự kết hợp của VCardDeliveryAddressType cờ (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"
    }
};

Số Điện Thoại

Số điện thoại tồn tại trong TelephoneNumbers bộ sưu tập như VCardTelephoneNumber các mục. Các TelephoneType thuộc tính nhận một sự kết hợp của VCardTelephoneType cờ (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, và hơn thế nữa).

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

Vị Trí Địa Lý

Cái Geo thuộc tính lưu trữ vị trí toàn cầu dưới dạng float vĩ độ và kinh độ.

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

Ảnh

Ảnh liên hệ được đặt trên IdentificationInfo.Photo Như một VCardPhoto. Nó có thể được nhúng trực tiếp từ byte ảnh hoặc tham chiếu bằng URL. Định dạng ảnh được xác định bởi VCardPhotoType và chế độ lưu trữ bằng 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
};

Nhãn Địa Chỉ Định Dạng

Nhãn là văn bản đã định dạng, sẵn sàng in của một địa chỉ giao hàng. Nhãn tồn tại trong Labels bộ sưu tập như VCardLabel các mục, mỗi mục được gắn thẻ với một loại địa chỉ.

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

Đọc lại Mô Hình

Sau khi tải vCard, cùng các tập hợp thuộc tính sẽ tiết lộ dữ liệu đã phân tích.

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

Bảo Mật (Khóa Công Khai hoặc Chứng Chỉ)

Cái Security tiết lộ khóa công khai hoặc chứng chỉ xác thực được lưu trong vCard (the KEY thuộc tính). Thuộc tính SaveToPEM phương thức ghi khóa đó vào tệp 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");
}

Tải một vCard

Sử dụng tĩnh VCardContact.Load phương thức để đọc vCard từ tệp hoặc luồng. Khi đã tải, các thuộc tính của danh bạ có sẵn qua cùng các tập hợp thuộc tính đã dùng khi tạo nó.

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

Tải với Mã Hoá Cụ Thể

Để kiểm soát mã hoá văn bản được sử dụng khi đọc, truyền một VCardLoadOptions đối tượng với PreferredEncoding tập hợp thuộc tính.

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

Đọc Nhiều Danh Bạ Từ Một Tệp Đơn

Một tệp vCard có thể chứa hơn một danh bạ. Sử dụng phương thức tĩnh IsMultiContacts phương thức để kiểm tra xem một tệp hoặc luồng có chứa nhiều danh bạ hay không, và LoadAsMultiple để đọc chúng tất cả vào một List<VCardContact>. Cả hai phương pháp đều có các overload cho tệp, luồng và tùy chọn tải:

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

Tải Danh Bạ Một Cách Không Đồng Bộ

Đối với danh sách danh bạ lớn hoặc các ứng dụng I/O-bound (máy tính để bàn, web, hoặc di động), VCardContact cung cấp tải không đồng bộ không làm chặn luồng gọi. Sử dụng LoadAsync cho một danh bạ duy nhất và LoadAsMultipleAsync cho một vài. Cả hai đều chấp nhận một 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);
}

Tùy chọn Lưu

Cái VCardSaveOptions lớp tùy chỉnh cách một danh bạ được ghi:

Version — phiên bản vCard đầu ra từ VCardVersion enumeration: V21 (vCard 2.1, mặc định), V30 (3.0), hoặc V40 (4.0).
PreferredTextEncoding — cách mã hoá được sử dụng khi ghi tệp.
UseExtensions — liệu mở rộng (X-) các thuộc tính có thể được ghi. Mặc định là true.
ProductId — giá trị được ghi vào PRODID thuộc tính.

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

Xem Thêm

Quản lý Danh bạ Outlook — tạo, lưu và đọc Outlook MapiContact các mục, bao gồm nhập và xuất VCF.
Quản lý Danh bạ trong các Tệp PST — lưu và đọc danh bạ trong PST.

Làm việc với các mục Outlook Làm việc với các tệp lưu trữ Outlook