עבודה עם קבצי vCard (VCF) ב‑C#

מאמר זה מכסה את VCardContact מחלקה מ‑ Aspose.Email.PersonalInfo.VCard מרחב שם, שקורא וכותב קבצי vCard (VCF) באופן עצמאי מ‑Outlook ו‑MAPI. ליצירה וניהול של Outlook MapiContact פריטים — שניתן גם לייצא ל‑VCF — ראה ניהול אנשי קשר של Outlook.

VCardContact מול 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, ו- 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 = "[e-mail]",
            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 = "[phone]",
        TelephoneType = VCardTelephoneType.WORK | VCardTelephoneType.VOICE
    },
    new VCardTelephoneNumber
    {
        TelephoneNumber = "[phone]",
        TelephoneType = VCardTelephoneType.CELL
    }
};

מיקום גאוגרפי

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

תוויות כתובת פורמטות

תווית היא הטקסט המופרמט, מוכן להדפסה של כתובת משלוח. תוויות קיימות ב‑ תוויות אוסף כ‑ 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 (ה‑ 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>. לשתי השיטות יש עומסי קבצים, זרמים ו‑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);
        }
    }
}

טעינת קשרים אסינכרונית

לרשימות קשרים גדולות או אפליקציות תלויות 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.