VcardOptions Class
Definition
Namespace: DataStandardizer.File.vCard
Options to configure the behaviour of a vCard reader or writer. The defaults follow RFC 6350, and a vCard 2.1 card follows its own specification. Each accommodation for common non-compliant input or output is a separate option, off by default. There is no single “lenient mode”.
.NET:
public sealed record VcardOptions
.NET Standard:
public sealed class VcardOptions
Properties
Each property is init on .NET and set on .NET Standard. A reader ignores the options that are only for writing, and a writer ignores those that are only for reading.
Reading
| Property | Type | Default | Notes |
|---|---|---|---|
AcceptBareLineFeed | bool | false | Accepts a bare line feed as a line break, both to end a line and in a fold. RFC 6350 §3.2 and §3.3 require CRLF. A bare carriage return is never a line break. |
AcceptByteOrderMark | bool | false | Accepts and skips a byte order mark at the start of the data. The vcard rule of RFC 6350 §3.3 starts with BEGIN:VCARD, and RFC 3629 §6 says a protocol that mandates UTF-8 should forbid the signature. It never selects the encoding. |
AcceptCaretEncodingInAllVersions | bool | false | Decodes RFC 6868 caret encoding on every line. RFC 6868 updates RFC 6350, and not RFC 2426 or vCard 2.1, where a caret is an ordinary character. |
AcceptEightBitWithoutEncoding | bool | false | Decodes a value in a 2.1 card with characters outside US-ASCII and no ENCODING=8BIT. vCard 2.1 §2.1.5 makes 7-bit the default. The value must still be valid in its CHARSET. |
AcceptLegacySyntax | bool | false | Gives every line the lexical forms of vCard 2.1, which a 2.1 card has anyway: parameters with no name, soft line breaks, BASE64 lines, ENCODING and CHARSET. It also accepts a parameter with no name that vCard 2.1 §2.9 doesn’t allow, and an escape sequence that RFC 6350 §3.4 doesn’t have. VcardReader then accepts ENCODING and CHARSET in a 4.0 card and the typed members decode the value, but VcardWriter refuses to write such a card. See Handle legacy character sets. |
AcceptMissingFinalLineBreak | bool | false | Accepts a last line with no line break. The contentline rule of RFC 6350 §3.3 ends with CRLF. |
AcceptOrgUriProperty | bool | false | For VcardReader, reads a property named ORG-URI as ORG-DIRECTORY, so it is judged as that property and a writer writes that name. RFC 6715 §2.4 and IANA say ORG-DIRECTORY. The RFC as published also says ORG-URI in §3.1 and §5, which its errata 3340 and 3341 correct, so by default ORG-URI is an unknown property, kept in ExtensionProperties. |
AcceptRfc6350FoldsInVersion21 | bool | false | Unfolds a 2.1 card as RFC 6350 §3.2 does, removing one white space character. vCard 2.1 §2.1.3 keeps it. |
AcceptUnescapedCommasInUris | bool | false | For VcardReader, accepts a comma with no backslash in a URI value of a 4.0 card, and escapes it as the line is read, so the typed members give the value and a writer writes it escaped. RFC 6350 §3.4 says a comma “MUST be escaped”, and its errata 3845 and 3846, and RFC 6474’s errata 4557 and 4559, apply that to URI values. It doesn’t apply to a line with ENCODING or CHARSET. |
AllowVersionNotFirst | bool | false | Obsolete, and has no effect. A vCard 4.0 card whose VERSION isn’t immediately after BEGIN:VCARD (RFC 6350 §3.3 and §6.7.9) is never read, since the version says how the lines before it would be read. |
AllowUnknownCharsetAsLatin1 | bool | false | Decodes a value in a character set that can’t be resolved as ISO-8859-1. GetDecodedText(out bool) says it did. |
CharsetResolver | IMimeCharsetResolver? | null | Resolves the character sets that the built-in encodings and the runtime don’t. |
MaxLineLength | int? | null | The longest logical line allowed, in characters, not counting its line break. null means no limit, since RFC 6350 sets none. The reader keeps each logical line in memory, so a limit is recommended for untrusted data. A line with more folds than the limit is rejected too. It is checked as each line is read, so the = of a quoted-printable soft line break counts until it is removed. It must be at least 1. |
Writing
| Property | Type | Default | Notes |
|---|---|---|---|
AllowLossyVersionConversion | bool | false | Writes a parameter value that needs RFC 6868 caret encoding outside a 4.0 card without those characters: a double quote is left out, and a line break becomes one space. RFC 6868 updates RFC 6350 only, and the param-value rule of RFC 2426 §4 can’t hold them. The default throws VcardFileException. VcardWriter applies the same choice to a whole card: data that WriteVersion can’t hold throws by default, and with this is left out. |
WriteNamedTypesInVersion21 | bool | false | Writes each TYPE of a 2.1 card with its name, as TEL;TYPE=WORK;TYPE=VOICE:. vCard 2.1 §2.9 allows a knowntype with or without its name, and by default it is written alone, as TEL;WORK;VOICE:, which is the form of every example in the specification. A TYPE that isn’t a knowntype, and every other parameter, is written with its name either way. |
WriteVersion | VcardVersion | V4_0 | The version VcardWriter writes. V3_0 and V2_1 convert a card from the canonical form of the model; see Versions and canonical forms. Ignored by a reader and by VcardContentLineWriter. |
FoldLength | int | 75 | The length, in octets of the UTF-8 encoding and not counting the line break, at which lines are folded. RFC 6350 §3.2 says lines should be folded to 75, so a longer length relaxes that. A fold never splits a character. The minimum is 4. The lines of a 2.1 card are never folded. |
FoldWhitespace | char | ' ' | The white space at the start of each continuation line: a space or a horizontal tab, the two that RFC 6350 §3.2 allows. |
LineBreak | string | "\r\n" | The line break at the end of each physical line. RFC 6350 §3.2 and §3.3 require CRLF. A bare line feed, "\n", relaxes that, and no other value is accepted. |
Reading and writing
| Property | Type | Default | Notes |
|---|---|---|---|
AllowCardinalityViolations | bool | false | For VcardReader and VcardWriter, accepts a card that breaks the cardinality rules of RFC 6350 §6, or has a MEMBER without KIND:group (§6.6.5). A second VERSION isn’t accepted, since the version says how the card’s lines are read. |
AllowInvalidValues | bool | false | For VcardReader and VcardWriter, accepts a value or parameter that breaks RFC 6350 §4, §5 or §6: a value that doesn’t follow its syntax, a VALUE the property doesn’t allow, a parameter on a property that doesn’t allow it, a PREF outside 1 to 100, or a PID source with no CLIENTPIDMAP. A value with a character that can’t be written still can’t be. |
AllowMissingRequiredProperties | bool | false | For VcardReader and VcardWriter, accepts a card with no FN (RFC 6350 §6.2.1), a 3.0 card with no N or FN (RFC 2426 §5), a 2.1 card with no N (vCard 2.1 §2.2.2), or, reading, a card held in an AGENT with no VERSION, which takes the version of the card around it (as in RFC 2426 §3.5.4), and whose SourceVersion is then null. Any other card with no VERSION isn’t accepted, since nothing else says how its lines are read (§6.7.9). |
Encoding | Encoding? | null | Applies to a stream or file. null means strict UTF-8 with no byte order mark, as RFC 6350 §3.1 requires. Setting another encoding relaxes that rule, and the encoding is used as it is. For a reader, Encoding.UTF8 replaces invalid data instead of rejecting it. A reader never removes the encoding’s preamble, so a byte order mark is still accepted only by AcceptByteOrderMark. A writer writes the preamble of the encoding, if it has one. To read raw 8-bit vCard 2.1 values, set ISO-8859-1. Must be null with a TextReader or TextWriter. |
Applies to
Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0.