Praca z plikami vCard (VCF) w C#

Ten artykuł obejmuje VCardContact klasą z Aspose.Email.PersonalInfo.VCard przestrzeń nazw, która odczytuje i zapisuje pliki vCard (VCF) niezależnie od Outlooka i MAPI. Aby utworzyć i zarządzać Outlook MapiContact elementy — które również mogą być eksportowane do VCF — zobacz Zarządzanie kontaktami Outlook.

VCardContact vs MapiContact

Aspose.Email udostępnia kontakty poprzez dwie różne klasy, a wybór właściwej eliminuje wiele nieporozumień:

  • VCardContact (przestrzeń nazw Aspose.Email.PersonalInfo.VCard) — czysty obiekt vCard. Użyj go, gdy źródłem i celem są pliki vCard (VCF) i nie potrzebujesz funkcji Outlook/MAPI. Odczytuje i zapisuje VCF bezpośrednio, obsługuje vCard 2.1/3.0/4.0, wiele kontaktów w jednym pliku oraz asynchroniczne ładowanie.
  • MapiContact (przestrzeń nazw Aspose.Email.Mapi) — kontakt Outlook. Użyj go, gdy pracujesz z MSG/PST lub potrzebujesz właściwości specyficznych dla MAPI. MapiContact może także importować i eksportować VCF przez jego FromVCard i Save metodach (zobacz Zarządzanie kontaktami Outlook).

Reszta tego artykułu skupia się na VCardContact.

Utwórz vCard i zapisz go

Ten VCardContact klasa ma konstruktor bez parametrów i udostępnia silnie typowane zestawy właściwości, takie jak IdentificationInfo, Organizacja, E‑maile, TelephoneNumbers, oraz DeliveryAddresses.

Poniższy fragment kodu pokazuje, jak zbudować kontakt od podstaw i zapisać go jako plik 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");

Model właściwości kontaktu

Poza imieniem i e-mailem pokazanymi powyżej, VCardContact udostępnia pełny model danych vCard poprzez silnie typowane zestawy właściwości. Poniższe fragmenty kodu rozszerzają contact utworzonych wcześniej. Każdą kolekcję można zainicjować przy pomocy inicjalizatora kolekcji lub dodać do niej za pomocą Add.

Adresy pocztowe

Adresy pocztowe znajdują się w DeliveryAddresses kolekcję jako VCardDeliveryAddress elementów. AddressType właściwość przyjmuje kombinację VCardDeliveryAddressType flagi (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"
    }
};

Numery telefonów

Numery telefonów znajdują się w TelephoneNumbers kolekcję jako VCardTelephoneNumber elementów. TelephoneType właściwość przyjmuje kombinację VCardTelephoneType flagi (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, i więcej).

contact.TelephoneNumbers = new VCardTelephoneNumberCollection
{
    new VCardTelephoneNumber
    {
        TelephoneNumber = "(08) 9080 1183",
        TelephoneType = VCardTelephoneType.WORK | VCardTelephoneType.VOICE
    },
    new VCardTelephoneNumber
    {
        TelephoneNumber = "(925) 599 3355",
        TelephoneType = VCardTelephoneType.CELL
    }
};

Pozycja geograficzna

Ten Geo właściwość przechowuje globalną pozycję jako float szerokość i długość geograficzna.

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

Zdjęcie

Zdjęcie kontaktu ustawiane jest na IdentificationInfo.Photo jako VCardPhoto. Może być osadzona inline z bajtami obrazu lub odwołana przez URL. Format obrazu określany jest przez VCardPhotoType i tryb przechowywania przez 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
};

Sformatowane etykiety adresowe

Etykieta to sformatowany, gotowy do druku tekst adresu dostawy. Etykiety znajdują się w Labels kolekcję jako VCardLabel elementy, każdy oznaczony typem adresu.

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

Odczytaj model z powrotem

Po załadowaniu vCard, te same zestawy właściwości udostępniają przetworzone dane.

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

Bezpieczeństwo (klucz publiczny lub certyfikat)

Ten Security właściwość udostępnia klucz publiczny lub certyfikat uwierzytelniający przechowywany w vCard ( KEY właściwość). Jej SaveToPEM metoda zapisuje ten klucz do pliku 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");
}

Ładuj vCard

Użyj statycznej VCardContact.Load metoda odczytu vCard z pliku lub strumienia. Po załadowaniu właściwości kontaktu są dostępne poprzez te same zestawy właściwości użyte przy ich tworzeniu.

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

Ładuj z określonym kodowaniem

Aby kontrolować kodowanie tekstu używane podczas odczytu, przekaż VCardLoadOptions obiekt z jego PreferredEncoding zestaw właściwości.

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

Odczytaj wiele kontaktów z jednego pliku

Plik vCard może zawierać więcej niż jeden kontakt. Użyj statycznej IsMultiContacts metoda sprawdzająca, czy plik lub strumień zawiera wiele kontaktów, oraz LoadAsMultiple aby odczytać je wszystkie do List<VCardContact>. Obie metody mają przeciążenia dla pliku, strumienia i opcji ładowania:

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

Ładuj kontakty asynchronicznie

Dla dużych list kontaktów lub aplikacji o dużym obciążeniu I/O (desktop, web lub mobile), VCardContact zapewnia asynchroniczne ładowanie, które nie blokuje wątku wywołującego. Użyj LoadAsync dla pojedynczego kontaktu i LoadAsMultipleAsync dla kilku. Oba akceptują 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);
}

Opcje zapisu

Ten VCardSaveOptions klasa dostosowuje sposób zapisu kontaktu:

  • Version — wersja wyjściowa vCard z VCardVersion enumeracji: V21 (vCard 2.1, domyślnie), V30 (3.0), lub V40 (4.0).
  • PreferredTextEncoding — kodowanie używane przy zapisywaniu pliku.
  • UseExtensions — czy rozszerzone (X-) właściwości mogą być zapisywane. Domyślnie to true.
  • ProductId — wartość zapisana do PRODID właściwość.
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);

Zobacz także

Praca z elementami Outlook Praca z plikami magazynu Outlook