کار با پرونده‌های 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 وارد و به 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 = "BerthaABuell@example.com",
            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 = "(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
};

عکس

یک عکس مخاطب روی 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 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);
        }
    }
}

بارگذاری مخاطبان به‌صورت ناهمزمان

برای فهرست‌های بزرگ مخاطب یا برنامه‌های 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 نوع شمارشی: 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