العمل مع ملفات 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 الصف يحتوي على مُنشئ بدون معلمات ويكشف عن مجموعات خصائص ذات نوع قوي مثل معلومات التعريف, المؤسسة, البريد الإلكتروني, 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}");
}

الأمان (المفتاح العام أو الشهادة)

الـ الأمان الخاصية تكشف عن المفتاح العام أو شهادة المصادقة المخزنة في 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>. كلا الطريقتين لهما ازدواجية للملف، الدفق، وخيارات التحميل:

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

تحميل جهات الاتصال بشكل غير متزامن

للقوائم الكبيرة من جهات الاتصال أو التطبيقات التي تعتمد على الإدخال/الإخراج (سطح المكتب، الويب، أو الجوال)، 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 تعداد: 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.