ทำงานกับไฟล์ vCard (VCF) ใน C#

บทความนี้ครอบคลุม VCardContact คลาสจาก Aspose.Email.PersonalInfo.VCard namespace ซึ่งอ่านและเขียนไฟล์ vCard (VCF) โดยอิสระจาก Outlook และ MAPI เพื่อสร้างและจัดการ Outlook MapiContact รายการ — ที่สามารถส่งออกเป็น VCF ได้ — ดู การจัดการรายชื่อผู้ติดต่อ Outlook.

VCardContact กับ MapiContact

Aspose.Email เปิดเผยข้อมูลติดต่อผ่านสองคลาสที่แตกต่างกัน การเลือกคลาสที่เหมาะสมจะช่วยหลีกเลี่ยงความสับสนจำนวนมาก

VCardContact (namespace Aspose.Email.PersonalInfo.VCard) — วัตถุ vCard สด ใช้เมื่อแหล่งและเป้าหมายเป็นไฟล์ vCard (VCF) และไม่ต้องการฟีเจอร์ Outlook/MAPI อ่านและเขียน VCF โดยตรง รองรับ vCard 2.1/3.0/4.0 หลายข้อมูลติดต่อต่อไฟล์ และการโหลดแบบอะซิงโครนัส
MapiContact (namespace Aspose.Email.Mapi) — ข้อมูลติดต่อ Outlook ใช้เมื่อทำงานกับ MSG/PST หรือจำเป็นต้องใช้คุณสมบัติ MAPI‑specific MapiContact ยังสามารถนำเข้าและส่งออกเป็น VCF ผ่าน FromVCard และ Save วิธี (ดู การจัดการรายชื่อผู้ติดต่อ Outlook).

ส่วนที่เหลือของบทความนี้เน้นที่ VCardContact.

สร้าง vCard และบันทึกมัน

นี้ VCardContact คลาสมีคอนสตรัคเตอร์โดยไม่มีพารามิเตอร์และเปิดเผยชุดคุณสมบัติแบบ strongly‑typed เช่น 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 ทั้งหมดผ่านชุดคุณสมบัติแบบ strongly‑typed ตัวอย่างโค้ดด้านล่างขยาย 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
    }
};

ตำแหน่งภูมิศาสตร์

นี้ Geo คุณสมบัติเก็บตำแหน่งทั่วโลกเป็น float ละติจูดและลองจิจูด

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

Photo

รูปถ่ายของข้อมูลติดต่อถูกตั้งค่าใน 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 คุณสมบัติเปิดเผยคีย์สาธารณะหรือใบรับรองการรับรองที่เก็บไว้ใน vCard (the 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

ใช้ static 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 อาจมีข้อมูลติดต่อมากกว่าหนึ่งรายการ ใช้ static 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 enumeration: 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 MapiContact รายการ รวมถึงการนำเข้าและส่งออก VCF
การจัดการรายชื่อผู้ติดต่อในไฟล์ PST — เก็บและอ่านข้อมูลติดต่อภายใน PST

ทำงานกับรายการ Outlook ทำงานกับไฟล์ที่เก็บข้อมูล Outlook