DataStandardizer.File.vCard
Reading and writing of vCard data, in the .vcf format of vCard 4.0, 3.0 and 2.1 and in its JSON (jCard) and XML (xCard) forms, with conversion between the versions.
dotnet add package DataStandardizer.File.vCard
Standards
| Standard | What it provides |
|---|---|
| RFC 6350 | vCard Format Specification: the content-line syntax, including groups, line folding and TEXT escaping; the typed values of §4; and the properties and parameters of §5 and §6, with their conformance rules. |
| RFC 6868 | Parameter Value Encoding in iCalendar and vCard: caret encoding of double quotes and line breaks in parameter values. |
| RFC 7095 | jCard: The JSON Format for vCard: reading and writing cards as JSON with JcardReader and JcardWriter, which aren’t on netstandard1.1, and the jCard form of the typed values, VcardValueFormat.Json, which is on every target. See Read and write jCard. |
| RFC 6351 | xCard: vCard XML Representation: reading and writing cards as XML with XcardReader and XcardWriter, on every target, and the xCard form of the typed values, VcardValueFormat.Xml. See Read and write xCard. |
| vCard 2.1 | The Electronic Business Card: vCard 2.1 cards, including quoted-printable, BASE64, CHARSET, parameters with no name and the card an AGENT holds. See Handle legacy character sets and Versions and canonical forms. |
| RFC 2425, RFC 2426 | vCard MIME Directory Profile: vCard 3.0 cards, with their errata. See Versions and canonical forms. |
| RFC 2739 | Calendar Attributes for vCard and LDAP: FBURL, CALADRURI, CAPURI and CALURI in vCard 3.0. |
| RFC 4770 | vCard Extensions for Instant Messaging: IMPP in vCard 3.0. |
| RFC 9554 | vCard Format Extensions for JSContact: CREATED, GRAMGENDER, LANGUAGE, PRONOUNS and SOCIALPROFILE; the parameters AUTHOR, AUTHOR-NAME, CREATED, DERIVED, LABEL, PHONETIC, PROP-ID, SCRIPT, SERVICE-TYPE and USERNAME; the TYPE values billing and delivery; and the added components of N and ADR. |
| RFC 6473, RFC 6869 | vCard KIND:application and vCard KIND:device: two more kinds of card. |
| RFC 6474 | vCard Format Extensions: Place of Birth, Place and Date of Death: BIRTHPLACE, DEATHPLACE and DEATHDATE. |
| RFC 6715 | vCard Format Extensions: Representing vCard Extensions Defined by the Open Mobile Alliance (OMA) Converged Address Book (CAB) Group: EXPERTISE, HOBBY, INTEREST, ORG-DIRECTORY, LEVEL and INDEX. |
| RFC 8605 | vCard Format Extensions: ICANN Extensions for the Registration Data Access Protocol (RDAP): CONTACT-URI and CC. |
The readers and writers follow these standards by default. A reader rejects a card that breaks a MUST or MUST NOT rule, and a writer refuses to write one. A vCard 3.0 or 2.1 card is held to the rules of its own version. Each accommodation for common non-compliant input is a separate option on VcardOptions that you turn on by name. So a file that other software reads without complaint may need one, for example AcceptByteOrderMark for a file saved with a byte order mark. See Standards compliance by default.
JSContact itself (RFC 9553) isn’t implemented, and nor are the vCard properties and parameters of RFC 9555 that carry it. They are kept and written back like any other property or parameter the package doesn’t know.
Platform support
Targets .NET Standard 1.1, 2.0 and 2.1, and .NET 10.
Applies to: the async API and the file-path constructors need .NET Standard 2.0 or later. jCard (
JcardReaderandJcardWriter) needs .NET Standard 2.0 or later too. On .NET Standard 1.1, read and write synchronously, from aStream,TextReaderorTextWriter. xCard is on every target.VcardOptionsis arecordonnet10.0, sowithexpressions work there, and a plainclasson the .NET Standard targets.
The package depends on DataStandardizer.Communication for media types, character sets, base64 and quoted-printable, which brings in DataStandardizer.LanguageTag, DataStandardizer.Geography and DataStandardizer.Language.
See Platform support for the full matrix.
How-to guides
- Read and write .vcf files
- Read asynchronously
- Read with zero copies
- Convert between 4.0, 3.0 and 2.1
- Convert between .vcf, jCard and xCard
- Read non-compliant cards
- Handle legacy character sets
- Read and write jCard
- Read and write xCard
Concepts
- The layered model
- The common model and the versioned interfaces
- Versions and canonical forms
- PREF, PID and ALTID
- Standards compliance by default
- The shared content-line engine
Reference
Table of contents
- Read and write .vcf files
- Read asynchronously
- Read with zero copies
- Convert between versions
- Convert formats
- Read non-compliant cards
- Handle legacy character sets
- jCard (JSON)
- xCard (XML)
- The layered model
- Common model and versioned interfaces
- Versions and canonical forms
- PREF, PID and ALTID
- Standards compliance by default
- The shared content-line engine
- API reference
- IVcard21Card Interface
- IVcard21Property Interface
- IVcard21PropertyList Interface
- IVcard30Card Interface
- IVcard30Property Interface
- IVcard30PropertyList Interface
- IVcard40Card Interface
- IVcard40Property Interface
- IVcard40PropertyList Interface
- JcardReader Class
- JcardWriter Class
- Vcard21PropertyParameters Class
- Vcard30PropertyParameters Class
- VcardAddress Struct
- VcardAgent Class
- VcardCard Class
- VcardCardinality Enum
- VcardClientPidMap Struct
- VcardComponentEnumerator Struct
- VcardComponentView Struct
- VcardContentLine Class
- VcardContentLineParameter Class
- VcardContentLineReader Class
- VcardContentLineView Struct
- VcardContentLineWriter Class
- VcardDate Struct
- VcardDateAndOrTime Struct
- VcardDateAndOrTimeKind Enum
- VcardDateTime Struct
- VcardDiagnostic Class
- VcardDiagnosticKind Enum
- VcardFileException Class
- VcardGender Struct
- VcardGeo Struct
- VcardKind Enum
- VcardLegacyMediaTypes Class
- VcardLegacySyntax Enum
- VcardLevel Enum
- VcardListEnumerator Struct
- VcardMediaUri Class
- VcardMediaValue Class
- VcardName Struct
- VcardOptions Class
- VcardOrganization Struct
- VcardParameterNames Class
- VcardPhoneticSystem Enum
- VcardPid Struct
- VcardProperty Class
- VcardPropertyInfo Class
- VcardPropertyList Class
- VcardPropertyNames Class
- VcardPropertyParameters Class
- VcardReader Class
- VcardSex Enum
- VcardStructuredValueView Struct
- VcardTime Struct
- VcardTimestamp Struct
- VcardTypedValue Struct
- VcardUtcOffset Struct
- VcardValue Class
- VcardValueFormat Enum
- VcardValueType Enum
- VcardValueTypeRegistry Class
- VcardVersion Enum
- VcardVersionConverter Class
- VcardWriteProgress Struct
- VcardWriter Class
- XcardReader Class
- XcardWriter Class