C#에서 vCard(VCF) 파일 작업

이 문서는 VCardContact 클래스는 Aspose.Email.PersonalInfo.VCard 네임스페이스, Outlook 및 MAPI와 무관하게 vCard(VCF) 파일을 읽고 씁니다. Outlook을 생성하고 관리하려면 MapiContact 항목 — VCF로 내보낼 수도 있습니다 — 참조 Outlook 연락처 관리.

VCardContact vs 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를 통해 가져오고 내보낼 수도 있습니다. FromVCard 및 Save 메서드에 초점을 맞춥니다(참조 Outlook 연락처 관리).

이 문서의 나머지 부분은 VCardContact.

vCard 생성 및 저장

다음은 VCardContact 클래스는 매개변수 없는 생성자를 가지고 있으며 다음과 같은 강력히 형식화된 속성 집합을 노출합니다. IdentificationInfo, 조직, 이메일, 전화번호, 그리고 배송 주소.

다음 코드 스니펫은 처음부터 연락처를 만들고 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.

우편 주소

우편 주소는 배송 주소 컬렉션을 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"
    }
};

전화 번호

전화번호는 전화번호 컬렉션을 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
};

포맷된 주소 레이블

레이블은 배송 주소의 포맷된 인쇄 준비 텍스트입니다. 레이블은 레이블 컬렉션을 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}");
}

보안(공개 키 또는 인증서)

다음은 보안 속성은 vCard에 저장된 공개 키 또는 인증서(의 KEY 속성). 해당 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 저장소 파일 작업