IEnumerableExtensionToVcfString Method

Serializes vCards as a String, which represents the content of a VCF file.

Definition

Namespace: FolkerKinzel.VCards.Extensions
Assembly: FolkerKinzel.VCards (in FolkerKinzel.VCards.dll) Version: 8.0.1+a91cc3f0fd39aeb548e16006a60ca9dd10a304a2

public static string ToVcfString(
	this IEnumerable<VCard?> vCards,
	VCdVersion version = VCdVersion.V3_0,
	ITimeZoneIDConverter? tzConverter = null,
	VcfOpts options = VcfOpts.Default
)

<ExtensionAttribute>
Public Shared Function ToVcfString ( 
	vCards As IEnumerable(Of VCard),
	Optional version As VCdVersion = VCdVersion.V3_0,
	Optional tzConverter As ITimeZoneIDConverter = Nothing,
	Optional options As VcfOpts = VcfOpts.Default
) As String

C++

public:
[ExtensionAttribute]
static String^ ToVcfString(
	IEnumerable<VCard^>^ vCards, 
	VCdVersion version = VCdVersion::V3_0, 
	ITimeZoneIDConverter^ tzConverter = nullptr, 
	VcfOpts options = VcfOpts::Default
)

[<ExtensionAttribute>]
static member ToVcfString : 
        vCards : IEnumerable<VCard> * 
        ?version : VCdVersion * 
        ?tzConverter : ITimeZoneIDConverter * 
        ?options : VcfOpts 
(* Defaults:
        let _version = defaultArg version VCdVersion.V3_0
        let _tzConverter = defaultArg tzConverter null
        let _options = defaultArg options VcfOpts.Default
*)
-> string

Parameters

vCards IEnumerableVCard: The VCard objects to be serialized. The collection may be empty or may contain null values.
version VCdVersion (Optional): The vCard version used for the serialization.
tzConverter ITimeZoneIDConverter (Optional): An object that implements ITimeZoneIDConverter to convert IANA time zone names to UTC offsets, or null.
options VcfOpts (Optional): Options for serializing VCF. The flags can be combined.

Return Value

String
vCards, serialized as a String, which represents the content of a VCF file.

Usage Note

In Visual Basic and C#, you can call this method as an instance method on any object of type IEnumerableVCard. When you use instance method syntax to call this method, omit the first parameter. For more information, see Extension Methods (Visual Basic) or Extension Methods (C# Programming Guide).

Remarks

Caution

Although the method itself is thread-safe, the VCard objects passed to the method are not. Block read and write access to these VCard objects, while this method is being executed!

The method may serialize more vCards than the number of elements in the collection passed to the vCards parameter. This can happen if there are embedded VCard objects in the Members or Relations properties.

Example

using FolkerKinzel.VCards;
using FolkerKinzel.VCards.Enums;
using FolkerKinzel.VCards.Extensions;
using FolkerKinzel.VCards.Models.Properties;

namespace Examples;

public class ExtensionMethodExample
{
    public static void Example()
    {
        VCard vc = InitializeTestVCard();

        Console.WriteLine("The content of vc is:\n");
        Console.WriteLine(vc);
        Console.WriteLine("\n=====================================\n");

        // (The extension methods will do all the necerssary
        // null checking.)

        // Group properties by their group name. (Group names are
        // case insensitive.)
        Console.WriteLine("\nProperty values with the group name g1:");

        IGrouping<string?, KeyValuePair<Prop, VCardProperty>> g1Group =
            vc.Groups.First(x => x.Key == "g1");

        foreach (KeyValuePair<Prop, VCardProperty> kvp in g1Group)
        {
            Console.WriteLine("  {0}: {1}", kvp.Key, kvp.Value);
        };

        Console.WriteLine("\nDisplayNames ordered by Preference:");
        foreach (TextProperty dn in vc.DisplayNames.OrderByPref())
        {
            Console.WriteLine("  {0}", dn);
        }

        Console.WriteLine("\nThe most preferred DisplayName is: {0}", vc.DisplayNames.PrefOrNull());

        Console.WriteLine("\nDisplayNames ordered by Index:");
        foreach (TextProperty dn in vc.DisplayNames.OrderByIndex())
        {
            Console.WriteLine("  {0}", dn);
        }

        Console.WriteLine("\nThe DisplayName with the lowest Index is: {0}", vc.DisplayNames.FirstOrNull());

        // Group VCardProperties by their AltID parameter:
        Console.WriteLine("\nThe following display names mean the same in different languages:");

        IGrouping<string?, TextProperty> altIDQuery =
            vc.DisplayNames.GroupByAltID()
                           .First(x => x.Key == "@1");

        foreach (TextProperty prop in altIDQuery)
        {
            Console.WriteLine("  {0}", prop);
        }

        // Serialize the VCard as VCF. (Most of the methods of the Vcf class are also
        // available as extension methods.)
        Console.WriteLine("\nvc as vCard 3.0:\n");
        Console.WriteLine(vc.ToVcfString(options: VcfOpts.Default.Unset(VcfOpts.UpdateTimeStamp)));
    }

    private static VCard InitializeTestVCard()
    {
        return VCardBuilder
            .Create(setContactID: false)
            .DisplayNames.Add("vCard zum Testen",
                               parameters:
                               p =>
                               {
                                   p.Language = "de";
                                   p.AltID = "@1";
                                   p.Index = 2;
                               }
                             )
            .DisplayNames.Add("vCard for testing",
                               parameters:
                               p =>
                               {
                                   p.Language = "en";
                                   p.AltID = "@1";
                               }
                             )
            .DisplayNames.Add("Something else",
                               parameters: p => p.Index = 1
                             )
            // The properties of the VCard class that contain collections allow
            // null references within these collections. Extension methods undertake
            // the necessary null checking when reading these properties:
            .DisplayNames.Edit(dplayNames => dplayNames.Append(null))
            .Phones.Add("1234",
                        // The ParameterSection.PropertyClass property is of Type
                        // Nullable<PCl>. Use extension methods to edit such properties
                        // safely.
                        parameters: p => p.PropertyClass = p.PropertyClass.Set(PCl.Home),
                        group: vc => "g1"
                        )
            .TimeZones.Add("Europe/Berlin", group: vc => "G1")
            .VCard;
    }
}

/*
Console Output:

The content of vc is:

Version: 2.1

[Preference: 1]
[Language: en]
[AltID: @1]
DisplayNames: vCard for testing

[Preference: 2]
[Language: de]
[AltID: @1]
[Index: 2]
DisplayNames: vCard zum Testen

[Index: 1]
DisplayNames: Something else

[Group: G1]
TimeZones: Europe/Berlin

[PropertyClass: Home]
[Group: g1]
Phones: 1234

=====================================


Property values with the group name g1:
  Phones: 1234
  TimeZones: Europe/Berlin

DisplayNames ordered by Preference:
  vCard for testing
  vCard zum Testen
  Something else

The most preferred DisplayName is: vCard for testing

DisplayNames ordered by Index:
  Something else
  vCard zum Testen
  vCard for testing

The DisplayName with the lowest Index is: Something else

The following display names mean the same in different languages:
  vCard for testing
  vCard zum Testen

vc as vCard 3.0:

BEGIN:VCARD
VERSION:3.0
G1.TZ:+01:00
FN;LANGUAGE=en:vCard for testing
N:?;;;;
g1.TEL;TYPE=HOME:1234
END:VCARD
 */

Exceptions

ArgumentNullException	vCards is null.
ArgumentOutOfRangeException	version is not a defined value of the VcfOpts enum.
OutOfMemoryException	The system is out of memory.