Bekerja dengan File vCard (VCF) di C#

Artikel ini mencakup VCardContact kelas dari Aspose.Email.PersonalInfo.VCard namespace, yang membaca dan menulis file vCard (VCF) secara independen dari Outlook dan MAPI. Untuk membuat dan mengelola Outlook MapiContact item — yang juga dapat diekspor ke VCF — lihat Manajemen Kontak Outlook.

VCardContact vs MapiContact

Aspose.Email menampilkan kontak melalui dua kelas berbeda, dan memilih yang tepat menghindari banyak kebingungan:

  • VCardContact (namespace Aspose.Email.PersonalInfo.VCard) — objek vCard murni. Gunakan ini ketika sumber dan target Anda adalah file vCard (VCF) dan Anda tidak memerlukan fitur Outlook/MAPI. Ini membaca dan menulis VCF secara langsung, mendukung vCard 2.1/3.0/4.0, beberapa kontak per file, dan pemuatan asinkron.
  • MapiContact (namespace Aspose.Email.Mapi) — sebuah kontak Outlook. Gunakan ini ketika Anda bekerja dengan MSG/PST atau membutuhkan properti spesifik MAPI. MapiContact juga dapat mengimpor dari dan mengekspor ke VCF melalui FromVCard dan Save metode (lihat Manajemen Kontak Outlook).

Sisa artikel ini berfokus pada VCardContact.

Buat vCard dan Simpan

The VCardContact kelas memiliki konstruktor tanpa parameter dan menampilkan kumpulan properti bertipe kuat seperti InformasiIdentifikasi, Organisasi, Email, TelephoneNumbers, dan DeliveryAddresses.

Potongan kode berikut menunjukkan cara membuat kontak dari awal dan menyimpannya sebagai file 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");

Model Properti Kontak

Selain nama dan email yang ditunjukkan di atas, sebuah VCardContact menampilkan model data vCard lengkap melalui kumpulan properti bertipe kuat. Potongan kode di bawah memperluas contact dibuat sebelumnya. Setiap koleksi dapat diberikan inisialisasi koleksi atau ditambahkan dengan Add.

Alamat Pos

Alamat pos berada di dalam DeliveryAddresses koleksi sebagai VCardDeliveryAddress item. The AddressType properti mengambil kombinasi dari VCardDeliveryAddressType bendera (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"
    }
};

Nomor Telepon

Nomor telepon berada di dalam TelephoneNumbers koleksi sebagai VCardTelephoneNumber item. The TelephoneType properti mengambil kombinasi dari VCardTelephoneType bendera (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, dan lainnya).

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

Posisi Geografis

The Geo properti menyimpan posisi global sebagai float lintang dan bujur.

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

Foto

Foto kontak diatur pada IdentificationInfo.Photo sebagai sebuah VCardPhoto. Itu dapat disematkan secara inline dari byte gambar atau direferensikan oleh URL. Format gambar diberikan oleh VCardPhotoType dan mode penyimpanan oleh 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
};

Label Alamat Terformat

Label adalah teks terformat, siap cetak untuk alamat pengiriman. Label berada di dalam Label koleksi sebagai VCardLabel item, masing-masing ditandai dengan tipe alamat.

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

Baca Model Kembali

Setelah memuat vCard, kumpulan properti yang sama menampilkan data yang diurai.

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

Keamanan (Kunci Publik atau Sertifikat)

The Keamanan properti menampilkan kunci publik atau sertifikat otentikasi yang disimpan di vCard (the KEY properti). Ini SaveToPEM metode menulis kunci itu ke file 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");
}

Muat sebuah vCard

Gunakan statis VCardContact.Load metode untuk membaca vCard dari file atau stream. Setelah dimuat, properti kontak tersedia melalui kumpulan properti yang sama digunakan saat membuatnya.

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

Muat dengan Enkoding Khusus

Untuk mengontrol enkoding teks yang digunakan saat membaca, berikan sebuah VCardLoadOptions objek dengan PreferredEncoding set properti.

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

Baca Beberapa Kontak dari Satu File

Sebuah file vCard dapat berisi lebih dari satu kontak. Gunakan statis IsMultiContacts metode untuk memeriksa apakah file atau stream berisi banyak kontak, dan LoadAsMultiple untuk membacanya semua ke dalam sebuah List<VCardContact>. Kedua metode memiliki overload file, stream, dan load-options:

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

Muat Kontak Secara Asinkron

Untuk daftar kontak besar atau aplikasi I/O-bound (desktop, web, atau seluler), VCardContact menyediakan pemuatan asinkron yang tidak memblokir thread pemanggil. Gunakan LoadAsync untuk satu kontak dan LoadAsMultipleAsync untuk beberapa. Keduanya menerima sebuah 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);
}

Opsi Simpan

The VCardSaveOptions kelas menyesuaikan cara sebuah kontak ditulis:

  • Version — versi vCard keluaran dari VCardVersion enumerasi: V21 (vCard 2.1, default), V30 (3.0), atau V40 (4.0).
  • PreferredTextEncoding — enkoding yang digunakan saat menulis file.
  • UseExtensions — apakah diperluas (X-) properti dapat ditulis. Defaultnya adalah true.
  • ProductId — nilai yang ditulis ke PRODID properti.
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);

Lihat Juga

Bekerja dengan Item Outlook Bekerja dengan File Penyimpanan Outlook