C#でのvCard（VCF）ファイルの操作

この記事では VCardContact クラスは Aspose.Email.PersonalInfo.VCard 名前空間は Outlook や MAPI に依存せずに vCard（VCF）ファイルを読み書きします。Outlook の MapiContact アイテム — こちらも VCF にエクスポート可能 — 参照 Outlook 連絡先管理.

VCardContact と MapiContact の比較

Aspose.Email は連絡先を 2 つの異なるクラスで公開しており、適切なクラスを選択することで多くの混乱を防げます:

  • 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, 組織, メール, TelephoneNumbers、および DeliveryAddresses.

次のコードスニペットは、ゼロから連絡先を作成し、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.

郵便住所

郵便住所は DeliveryAddresses コレクションは 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"
    }
};

電話番号

電話番号は TelephoneNumbers コレクションは 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 ストレージ ファイルの操作