Práce se soubory vCard (VCF) v C#

Tento článek pokrývá VCardContact třídy z Aspose.Email.PersonalInfo.VCard namespace, který čte a zapisuje soubory vCard (VCF) nezávisle na Outlook a MAPI. Pro vytvoření a správu Outlook MapiContact položky — které lze také exportovat do VCF — viz Správa kontaktů Outlook.

VCardContact vs MapiContact

Aspose.Email zpřístupňuje kontakty přes dvě různé třídy a výběr té správné zabraňuje spoustě zmatků:

  • VCardContact (namespace Aspose.Email.PersonalInfo.VCard) — čistý objekt vCard. Použijte, když jsou vaším zdrojem i cílem soubory vCard (VCF) a nepotřebujete funkce Outlook/MAPI. Čte a zapisuje VCF přímo, podporuje vCard 2.1/3.0/4.0, více kontaktů v souboru a asynchronní načítání.
  • MapiContact (namespace Aspose.Email.Mapi) — kontakt Outlook. Použijte, když pracujete s MSG/PST nebo potřebujete vlastnosti specifické pro MAPI. MapiContact může také importovat a exportovat VCF přes jeho FromVCard a Save metody (viz Správa kontaktů Outlook).

Zbytek tohoto článku se zaměřuje na VCardContact.

Vytvořit vCard a uložit jej

The VCardContact třída má konstruktor bez parametrů a vystavuje silně typované sady vlastností jako IdentificationInfo, Organizace, E‑maily, TelephoneNumbers, a DeliveryAddresses.

Následující úryvek kódu ukazuje, jak vytvořit kontakt od začátku a uložit jej jako soubor 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 vlastností kontaktu

Kromě jména a e‑mailu uvedených výše, VCardContact zpřístupňuje celý datový model vCard pomocí silně typovaných sad vlastností. Níže uvedené úryvky rozšiřují contact vytvořené dříve. Každou sbírku lze přiřadit inicializátorem sbírky nebo doplnit Add.

Poštovní adresy

Poštovní adresy jsou v DeliveryAddresses sbírka jako VCardDeliveryAddress položek. Vlastnost AddressType vlastnost přijímá kombinaci VCardDeliveryAddressType příznaky (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"
    }
};

Telefonní čísla

Telefonní čísla jsou v TelephoneNumbers sbírka jako VCardTelephoneNumber položek. Vlastnost TelephoneType vlastnost přijímá kombinaci VCardTelephoneType příznaky (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, a více).

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

Geografická pozice

The Geo vlastnost ukládá globální polohu jako float zeměpisná šířka a délka.

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

Foto

Fotografie kontaktu je nastavena na IdentificationInfo.Photo jako VCardPhoto. Může být vložen inline z bajtů obrázku nebo odkazován URL. Formát obrázku je určen VCardPhotoType a režim úložiště podle 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
};

Formátované adresní popisky

Popisek je formátovaný, připravený k tisku text doručovací adresy. Popisky žijí v Labels sbírka jako VCardLabel položky, každá označená typem adresy.

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

Přečíst model zpět

Po načtení vCard stejné sady vlastností vystavují rozebraná data.

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

Zabezpečení (veřejný klíč nebo certifikát)

The Security vlastnost vystavuje veřejný klíč nebo autentizační certifikát uložený ve vCard ( KEY vlastnost). Její SaveToPEM metoda zapíše tento klíč do PEM souboru.

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

Načíst vCard

Použijte statickou VCardContact.Load metoda pro načtení vCard ze souboru nebo proudu. Po načtení jsou vlastnosti kontaktu dostupné přes stejné sady vlastností, které byly použity při jejich vytváření.

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

Načíst se specifickým kódováním

Pro kontrolu textového kódování při čtení předávejte VCardLoadOptions objekt s jeho PreferredEncoding vlastnost sady.

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

Načíst více kontaktů z jednoho souboru

Soubor vCard může obsahovat více než jeden kontakt. Použijte statickou IsMultiContacts metoda pro kontrolu, zda soubor nebo proud obsahuje více kontaktů, a LoadAsMultiple načíst je všechny do List<VCardContact>. Obě metody mají přetížení pro soubor, proud a možnosti načítání:

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

Načíst kontakty asynchronně

Pro velké seznamy kontaktů nebo aplikace zaměřené na I/O (desktop, web nebo mobil), VCardContact poskytuje asynchronní načítání, které neblokuje volající vlákno. Použijte LoadAsync pro jeden kontakt a LoadAsMultipleAsync pro několik. Obě přijímají 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);
}

Možnosti uložení

The VCardSaveOptions třída upravuje, jak je kontakt zapsán:

  • Version — výstupní verze vCard z VCardVersion enumerace: V21 (vCard 2.1, výchozí), V30 (3.0), nebo V40 (4.0).
  • PreferredTextEncoding — kódování použité při zápisu souboru.
  • UseExtensions — zda rozšířené (X-) mohou být zapsány. Výchozí je true.
  • ProductId — hodnota zapsaná do PRODID vlastnost.
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);

Viz také

Práce s položkami Outlook Práce se soubory úložiště Outlook