C#'ta vCard (VCF) Dosyalarıyla Çalışma

Bu makale şunları kapsar VCardContact sınıfı Aspose.Email.PersonalInfo.VCard namespace, Outlook ve MAPI’den bağımsız olarak vCard (VCF) dosyalarını okur ve yazar. Outlook MapiContact öğeler — ki VCF’ye de dışa aktarılabilir — bkz. Outlook Kişi Yönetimi.

VCardContact ve MapiContact

Aspose.Email kişileri iki farklı sınıf üzerinden sunar ve doğru olanı seçmek çok fazla karışıklığı önler:

• VCardContact (namespace Aspose.Email.PersonalInfo.VCard) — saf bir vCard nesnesi. Kaynak ve hedefiniz vCard (VCF) dosyaları olduğunda ve Outlook/MAPI özelliklerine ihtiyacınız olmadığında kullanın. VCF’yi doğrudan okur ve yazar, vCard 2.1/3.0/4.0’ı destekler, dosya başına birden çok kişi ve asenkron yükleme sağlar.
• MapiContact (namespace Aspose.Email.Mapi) — bir Outlook kişisi. MSG/PST ile çalışırken veya MAPI’ye özgü özelliklere ihtiyacınız olduğunda kullanın. MapiContact aynı zamanda VCF’den içe aktarabilir ve dışa aktarabilir FromVCard ve Save yöntemleri (bkz. Outlook Kişi Yönetimi).

Bu makalenin geri kalanı şunlara odaklanır VCardContact.

Bir vCard Oluştur ve Kaydet

Bu VCardContact sınıfı parametresiz bir yapıcıya sahiptir ve şu gibi güçlü tipli özellik kümeleri sunar IdentificationInfo, Organizasyon, E-postalar, TelefonNumaraları, ve TeslimatAdresleri.

Aşağıdaki kod parçacığı bir kişiyi sıfırdan nasıl oluşturacağınızı ve vCard (VCF) dosyası olarak nasıl kaydedeceğinizi gösterir.

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

Kişi Özellik Modeli

Yukarıda gösterilen isim ve e-posta dışında, bir VCardContact tam vCard veri modelini güçlü tipli özellik kümeleri üzerinden açığa çıkarır. Aşağıdaki kod parçacıkları şunu genişletir contact daha önce oluşturulmuş. Her koleksiyon bir koleksiyon başlatıcı ile atanabilir veya şununla eklenebilir Add.

Posta Adresleri

Posta adresleri TeslimatAdresleri koleksiyon olarak VCardDeliveryAddress öğeler. AddressType özellik bir kombinasyon alır VCardDeliveryAddressType bayraklar (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"
    }
};

Telefon Numaraları

Telefon numaraları TelefonNumaraları koleksiyon olarak VCardTelephoneNumber öğeler. TelephoneType özellik bir kombinasyon alır VCardTelephoneType bayraklar (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, ve daha fazlası).

contact.TelephoneNumbers = new VCardTelephoneNumberCollection
{
    new VCardTelephoneNumber
    {
        TelephoneNumber = "[phone]",
        TelephoneType = VCardTelephoneType.WORK | VCardTelephoneType.VOICE
    },
    new VCardTelephoneNumber
    {
        TelephoneNumber = "[phone]",
        TelephoneType = VCardTelephoneType.CELL
    }
};

Coğrafi Konum

Bu Geo özellik konumu şöyle depolar float enle ve boylam.

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

Fotoğraf

Bir kişi fotoğrafı şunun üzerinde ayarlanır IdentificationInfo.Photo olarak VCardPhoto. Resim baytlarından satıriçi gömülebilir veya URL ile referans verilebilir. Resim formatı şu şekilde verilir VCardPhotoType ve depolama modunu 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
};

Biçimlendirilmiş Adres Etiketleri

Bir etiket, teslimat adresinin biçimlendirilmiş, basıma hazır metnidir. Etiketler Etiketler koleksiyon olarak VCardLabel öğeler, her biri bir adres türüyle etiketlenmiş.

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

Modeli Geri Oku

Bir vCard yüklendikten sonra aynı özellik kümeleri ayrıştırılmış verileri sunar.

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

Güvenlik (Genel Anahtar veya Sertifika)

Bu Güvenlik özelliği vCard içinde depolanan genel anahtarı veya kimlik doğrulama sertifikasını açığa çıkarır ( KEY özellik). Onun SaveToPEM yöntemi bu anahtarı bir PEM dosyasına yazar.

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

Bir vCard Yükle

Statik VCardContact.Load yöntemi bir vCard’ı dosyadan ya da akıştan okur. Yüklendikten sonra, kişinin özellikleri aynı özellik kümeleri aracılığıyla kullanılabilir.

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

Belirli Bir Kodlama ile Yükle

Okuma sırasında kullanılan metin kodlamasını kontrol etmek için bir VCardLoadOptions nesnesi kendi PreferredEncoding özellik kümesi.

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

Tek Bir Dosyadan Birden Fazla Kişi Oku

Bir vCard dosyası birden fazla kişi içerebilir. Statik IsMultiContacts yöntemi bir dosyanın veya akışın birden fazla kişi içerip içermediğini kontrol eder ve LoadAsMultiple hepsini bir List<VCardContact>. Her iki yöntemin de dosya, akış ve yükleme-seçenekleri aşırı yüklemeleri vardır:

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

Kişileri Asenkron Olarak Yükle

Büyük iletişim listeleri veya I/O ağırlıklı uygulamalar (masaüstü, web veya mobil) için, VCardContact çağıran iş parçacığını engellemeyen asenkron yükleme sağlar. Kullan LoadAsync tek bir kontak için ve LoadAsMultipleAsync birkaç için. Her ikisi de bir 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);
}

Kaydetme Seçenekleri

Bu VCardSaveOptions sınıfı bir kontak nasıl yazılacağını özelleştirir:

• Version — çıktının vCard sürümü VCardVersion enumerasyonu: V21 (vCard 2.1, varsayılan), V30 (3.0), veya V40 (4.0).
• PreferredTextEncoding — dosya yazılırken kullanılan kodlama.
• UseExtensions — genişletilmiş olup olmadığı (X-) özellikleri yazılabilir. Varsayılan şudur true.
• ProductId — değerin yazıldığı PRODID özellik.

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

Ayrıca Bakınız

• Outlook Kişi Yönetimi — Outlook’u oluşturur, kaydeder ve okur MapiContact öğeler, VCF içe/dışa aktarımını içeren.
• PST Dosyalarında Kişileri Yönetme — bir PST içinde kişileri depolar ve okur.