FolkerKinzel.VCards 5.0.0-beta.3

Prefix Reserved

.NET 5.0 .NET Standard 2.0 .NET Framework 4.0

This is a prerelease version of FolkerKinzel.VCards.

There is a newer version of this package available.
See the version list below for details.

dotnet add package FolkerKinzel.VCards --version 5.0.0-beta.3

NuGet\Install-Package FolkerKinzel.VCards -Version 5.0.0-beta.3

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="FolkerKinzel.VCards" Version="5.0.0-beta.3" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add FolkerKinzel.VCards --version 5.0.0-beta.3

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: FolkerKinzel.VCards, 5.0.0-beta.3"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

// Install FolkerKinzel.VCards as a Cake Addin
#addin nuget:?package=FolkerKinzel.VCards&version=5.0.0-beta.3&prerelease

// Install FolkerKinzel.VCards as a Cake Tool
#tool nuget:?package=FolkerKinzel.VCards&version=5.0.0-beta.3&prerelease

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

.NET library to read, write and convert VCF files that match the vCard standards 2.1, 3.0 and 4.0.

It allows

to load VCF files from the file system and to save them there,
to serialize VCF files from and to Streams and
to convert VCF files, that match the vCard versions 2.1, 3.0 and 4.0, to each other.

FolkerKinzel.VCards is used as a dependency in FolkerKinzel.Contacts.IO - an easy to use .NET-API to manage contact data of organizations and natural persons.

Project Reference and Release Notes

Overview

The Data Model Explained

The data model used by this API is aligned to the vCard 4.0 standard (RFC6350). This means, every read vCard of version 2.1 and 3.0 is internally converted to vCard 4.0. When saved and serialized, they are converted back. A vCard is represented by the VCard class.

The `VCardProperty` Class

The data model of the VCard class based on classes, that are derived from VCardProperty.

VCardProperty exposes the following members:

public abstract class VCardProperty
{
    public string? Group { get; set; }

    public ParameterSection Parameters { get; }

    public virtual object? Value { get; protected set; }
}

This reflects the structure of a data row in a VCF file:

group1.TEL;TYPE=home,voice;VALUE=uri:tel:+49-123-4567

In this example corresponds

group1 to VCardProperty.Group,
TEL;TYPE=home,voice;VALUE=uri to VCardProperty.Parameters and
tel:+49-123-4567 to VCardProperty.Value.

(Classes that are derived from VCardProperty hide the generic implementation of VCardProperty.Value in order to return derived classes instead of System.Object?.)

Naming Conventions

Most properties of the VCard class are collections. It has to do with, that many properties are allowed to have more than one instance per vCard (e.g. phone numbers, e-mail addresses). Such properties are named in Plural.</para>

A special feature are properties whose name ends with "Views": These are properties, which actually is only one instance per vCard allowed, but vCard 4.0 enables you to have different versions of that single instance (e.g. in different languages). You must set the same AltID parameter on each of them.

Usage of the Namespaces

The following code example provides tips for using the namespaces of the library.

// Publish this namespace - it contains the VCard class:
using FolkerKinzel.VCards;

// It's recommended to publish also this namespace -
// it contains useful extension methods:
using FolkerKinzel.VCards.Extensions;

// These two namespaces may be published, but it's not
// recommended as they contain lots of classes and enums:
// using FolkerKinzel.VCards.Models;
// using FolkerKinzel.VCards.Models.Enums;

// Instead of publishing the two namespaces above
// better use a namespace alias:
using VC = FolkerKinzel.VCards.Models;

namespace NameSpaceAliasDemos;

public static class NameSpaceAliasDemo
{
    public static void HowToUseTheNameSpaceAlias() =>
        _ = new VC::RelationTextProperty("Folker", VC::Enums.RelationTypes.Contact);
}

How the Library Handles Data Errors

Parse errors, caused by not well-formed VCF files, are silently ignored by the library: It reads as much as it can from such files.

The same is for errors caused by incompliant data when serializing the vCard: Because of the different vCard standards are not completely compliant, incompliant data is silently ignored when converting from one vCard standard to another. To minimize this kind of data loss, the library tries to preserve incompliant data using well-known x-name properties. The usage of such x-name properties can be controlled via options (VcfOptions).

Product	Compatible and additional computed target framework versions.
.NET	net5.0 is compatible. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed.
.NET Core	netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.0 is compatible. netstandard2.1 is compatible.
.NET Framework	net40 is compatible. net403 was computed. net45 was computed. net451 was computed. net452 was computed. net46 was computed. net461 is compatible. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	tizen40 was computed. tizen60 was computed.
Xamarin.iOS	xamarinios was computed.
Xamarin.Mac	xamarinmac was computed.
Xamarin.TVOS	xamarintvos was computed.
Xamarin.WatchOS	xamarinwatchos was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETFramework 4.0
- No dependencies.
.NETFramework 4.6.1
- FolkerKinzel.Strings (>= 5.1.0)
.NETStandard 2.0
- FolkerKinzel.Strings (>= 5.1.0)
.NETStandard 2.1
- FolkerKinzel.Strings (>= 5.1.0)
net5.0
- FolkerKinzel.Strings (>= 5.1.0)
net6.0
- FolkerKinzel.Strings (>= 5.1.0)
net7.0
- FolkerKinzel.Strings (>= 5.1.0)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on FolkerKinzel.VCards:

Package	Downloads
FolkerKinzel.Contacts.IO Small and easy to use framework for .NET to manage contact data of organizations and natural persons, including a data model and classes to persist it as vCard (*.vcf) or CSV.	5.9K

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on FolkerKinzel.VCards:

Repository	Stars
ONLYOFFICE/CommunityServer Free open source office suite with business productivity tools: document and project management, CRM, mail aggregator.	2.7K
shr670377723/CommunityServer-master	291

Version	Downloads	Last updated
7.4.5	30	11/24/2024
7.4.4	139	11/18/2024
7.4.3	78	11/14/2024
7.4.2	167	11/9/2024
7.4.1	197	11/3/2024
7.4.0	78	11/2/2024
7.4.0-beta.1	45	10/27/2024
7.3.0	467	10/20/2024
7.3.0-beta.2	42	10/17/2024
7.3.0-beta.1	52	10/13/2024
7.2.2	2,022	10/6/2024
7.2.1	832	9/14/2024
7.2.0	3,030	7/21/2024
7.2.0-beta.2	53	7/16/2024
7.2.0-beta.1	53	7/13/2024
7.1.2	2,235	6/17/2024
7.1.1	1,767	6/5/2024
7.1.0	127	6/2/2024
7.1.0-beta.2	63	5/26/2024
7.1.0-beta.1	60	5/23/2024
7.0.0	596	5/4/2024
7.0.0-beta.2	91	4/28/2024
7.0.0-beta.1	86	4/14/2024
6.2.1	1,428	4/11/2024
6.2.0	393	3/18/2024
6.2.0-beta.3	66	3/10/2024
6.2.0-beta.2	64	3/10/2024
6.2.0-beta.1	56	3/10/2024
6.1.0	2,823	11/7/2023
6.0.0	117	11/5/2023
6.0.0-beta.2	80	10/30/2023
6.0.0-beta.1	83	10/25/2023
5.0.0-beta.3	120	7/11/2023
5.0.0-beta.2	90	7/2/2023
5.0.0-beta.1	87	6/24/2023
4.0.0	49,782	1/30/2022
3.1.1	2,471	1/23/2022
3.1.0	3,710	12/25/2021
3.0.0	1,290	11/14/2021
3.0.0-beta.1	265	10/30/2021
3.0.0-alpha.2	176	9/8/2021
3.0.0-alpha.1	156	8/30/2021
2.2.0	9,099	6/11/2021
2.1.1	597	4/4/2021
2.1.0	855	3/6/2021
2.1.0-rc	258	2/27/2021
2.1.0-beta	275	2/10/2021
2.0.2-alpha	209	2/7/2021
2.0.0	630	1/30/2021
2.0.0-rc	795	1/25/2021
2.0.0-beta.2	205	1/20/2021
2.0.0-beta	257	1/8/2021
2.0.0-alpha	249	1/5/2021
1.4.4	738	9/19/2020
1.4.3	709	5/25/2020
1.4.2	716	5/5/2020