Arbeta med vCard (VCF)-filer i C#

Den här artikeln täcker VCardContact klass från Aspose.Email.PersonalInfo.VCard namnrymd, som läser och skriver vCard‑ (VCF‑)filer oberoende av Outlook och MAPI. För att skapa och hantera Outlook MapiContact objekt — som också kan exporteras till VCF — se Hantera Outlook-kontakter.

VCardContact vs MapiContact

Aspose.Email exponerar kontakter genom två olika klasser, och att välja rätt undviker mycket förvirring:

VCardContact (namnrymd Aspose.Email.PersonalInfo.VCard) — ett rent vCard‑objekt. Använd den när din källa och mål är vCard‑ (VCF‑)filer och du inte behöver Outlook/MAPI‑funktioner. Den läser och skriver VCF direkt, stöder vCard 2.1/3.0/4.0, flera kontakter per fil och asynkron laddning.
MapiContact (namnrymd Aspose.Email.Mapi) — en Outlook‑kontakt. Använd den när du arbetar med MSG/PST eller behöver MAPI‑specifika egenskaper. MapiContact kan också importera från och exportera till VCF via sin FromVCard och Save metoder (se Hantera Outlook-kontakter).

Resten av den här artikeln fokuserar på VCardContact.

Skapa en vCard och spara den

Den VCardContact klassen har en parameterlös konstruktor och exponerar starkt typade egenskapssatser såsom Identifikationsinfo, Organisation, E‑post, Telefonnummer, och Leveransadresser.

Följande kodsnutt visar hur du bygger en kontakt från grunden och sparar den som en vCard‑ (VCF‑)fil.

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

Kontakt‑egenskapsmodellen

Förutom namn och e‑post som visas ovan, en VCardContact exponerar hela vCard‑datamodellen genom starkt typade egenskapssatser. Snuttarna nedan utökar contact skapade tidigare. Varje samling kan tilldelas med en samlingsinitialiserare eller läggas till med Add.

Postadresser

Postadresser finns i Leveransadresser samling som VCardDeliveryAddress objekt. De AddressType egenskap tar en kombination av VCardDeliveryAddressType flaggor (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"
    }
};

Telefonnummer

Telefonnummer finns i Telefonnummer samling som VCardTelephoneNumber objekt. De TelephoneType egenskap tar en kombination av VCardTelephoneType flaggor (VOICE, WORK, HOME, CELL, FAX, PAGER, PREF, och mer).

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

Geografisk position

Den Geo egenskap lagrar en global position som float latitud och longitud.

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

Foto

En kontaktfoto sätts på IdentificationInfo.Photo som en VCardPhoto. Den kan bäddas in inline från bild‑byte eller refereras via URL. Bildformatet anges av VCardPhotoType och lagringsläget genom 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
};

Formaterade adressetiketter

En etikett är den formaterade, utskrivklara texten för en leveransadress. Etiketter finns i Etiketter samling som VCardLabel objekt, var och en märkt med en adress‑typ.

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

Läs tillbaka modellen

Efter att en vCard har laddats exponerar samma egenskapssatser den analyserade datan.

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

Säkerhet (publik nyckel eller certifikat)

Den Säkerhet egenskap exponerar den publika nyckeln eller autentiseringscertifikatet som lagras i vCard‑filen (den KEY egenskap). Dess SaveToPEM metod skriver den nyckeln till en PEM-fil.

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

Läs en vCard

Använd den statiska VCardContact.Load metod för att läsa en vCard från en fil eller en ström. När den har lästs är kontaktens egenskaper tillgängliga via samma egenskapssatser som användes när den skapades.

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

Läs med en specifik kodning

För att styra textkodningen som används vid läsning, skicka en VCardLoadOptions objekt med dess PreferredEncoding egenskapssatsen.

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

Läs flera kontakter från en enda fil

En vCard-fil kan innehålla mer än en kontakt. Använd den statiska IsMultiContacts metod för att kontrollera om en fil eller ström innehåller flera kontakter, och LoadAsMultiple för att läsa in dem alla i en List<VCardContact>. Båda metoderna har fil-, ström‑ och laddningsalternativ‑överladdningar:

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

Ladda kontakter asynkront

För stora kontaktlistor eller I/O‑tunga applikationer (desktop, web eller mobile), VCardContact ger asynkron laddning som inte blockerar anropande tråd. Använd LoadAsync för en enda kontakt och LoadAsMultipleAsync för flera. Båda accepterar en 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);
}

Sparalternativ

Den VCardSaveOptions klassen anpassar hur en kontakt skrivs:

Version — den utdata vCard-versionen från VCardVersion enumerationen: V21 (vCard 2.1, standard), V30 (3.0), eller V40 (4.0).
PreferredTextEncoding — kodningen som används vid skrivning av filen.
UseExtensions — huruvida utökad (X-) egenskaper kan skrivas. Standard är true.
ProductId — värdet som skrivs till PRODID egenskap.

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

Se även

Hantera Outlook-kontakter — skapa, spara och läsa Outlook MapiContact objekt, inklusive VCF-import och export.
Hantera kontakter i PST-filer — lagra och läsa kontakter i en PST.

Arbeta med Outlook‑objekt Arbeta med Outlook‑lagringsfiler