Table of Contents

DelimitedSerializer Class

Definition

Namespace
Bodu.Text.Delimited
Assembly
Bodu.Text.Delimited.dll
Package
Bodu.Text.Delimited 1.3.0
Source
DelimitedSerializer.Binder.cs

Provides methods for serializing collections of .NET records to delimited (RFC 4180 CSV/TSV) text and deserializing delimited text into records, shaped after System.Text.Json's JsonSerializer.

public static class DelimitedSerializer
Inheritance
DelimitedSerializer
Inherited Members

Remarks

A delimited document is an array of records, so the serializer maps an IEnumerable<T> whose element type is a POCO (mapped column-by-column to the header) or a positional string array. Column names honor PropertyNamingPolicy and the PropertyNameAttribute family. Each member name maps to one column, its most derived declaration: a property or field hidden with the new modifier is neither written nor read. A record type that maps two members to one column is rejected with DelimitedSerializationException before anything is read or written.

A dictionary is written as KeyValuePair<TKey, TValue> records, with Key and Value columns, and those records read back: although both members are get-only, each record is created through the pair's constructor from the fields of the two columns, matched by header name, as they are written, or by position with NoHeader, and a column the document lacks leaves its half at its default. The column of any other get-only member is written and not read back.

Field values convert with the invariant culture. An empty field, or one of white space only, binds null to a member of a nullable value type, such as Nullable<T> of int or of DateTime. A nullable char is the exception: only an empty field binds null to it, and any other field converts as it does for a char member, so a single space binds a space. Other members convert the text as it is: a string member keeps it, and a numeric or date member throws DelimitedSerializationException for it.

A member is written as one field, so its type must be a scalar: a string or character, a number, a bool, an enumeration, a date, time or time span, a Guid or a Uri, or object holding one. A record type with a member of any other type, such as a dictionary or a class with members of its own, whether the member is readable, writable or both, is rejected with DelimitedSerializationException by every Serialize, SerializeAsync, Deserialize and DeserializeAsyncEnumerableAsync overload, before anything is written or read; writing an object member that holds such a value throws too. No such value is written as its ToString() text, which does not read back.

Temporal values are written in invariant round-trip forms and read back equal: DateTime and DateTimeOffset with the O format, which keeps every tick and the kind or the offset; DateOnly as yyyy-MM-dd; TimeOnly as HH:mm:ss.fffffff; and TimeSpan with the constant c format. Reading also accepts the invariant general forms that earlier versions wrote.

In header mode the header row comes from the record type: a collection of POCO records writes the names of the record type's readable members before the first record, or on their own when the collection has no records. With NoHeader set, an empty collection writes nothing.

The buffered Serialize and Deserialize stream overloads and the buffered SerializeAsync mirror the sibling quartet libraries; there is no buffered DeserializeAsync, because the asynchronous read is DeserializeAsyncEnumerableAsync<TRecord>(Stream, DelimitedSerializerOptions?, CancellationToken). That method and the IAsyncEnumerable<T> serialize overload are truly incremental: records are parsed and yielded as stream chunks arrive, and written and flushed in bounded batches, so neither surface materializes the document.

Methods

DeserializeAsyncEnumerableAsync<TRecord>(Stream, DelimitedSerializerOptions?, CancellationToken)

Asynchronously deserializes the delimited content of the supplied stream, reading incrementally and yielding each record as soon as its terminating line ending has been read.

[RequiresUnreferencedCode("Reflection-based delimited serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based delimited serialization may require runtime code generation.")]
public static IAsyncEnumerable<TRecord> DeserializeAsyncEnumerableAsync<TRecord>(Stream source, DelimitedSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

source Stream

The source stream.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that cancels the operation.

Returns

IAsyncEnumerable<TRecord>

An asynchronous sequence of records.

Type Parameters

TRecord

The record type.

Remarks

The stream is consumed in segments: only the bytes of records not yet terminated remain buffered, so memory use is bounded by the longest single record rather than the document. A UTF-8 byte-order mark is skipped only at the start of the stream; a U+FEFF that starts a later record, whichever segment it starts, is field content, as it is for Deserialize<TRecord>(Stream, DelimitedSerializerOptions?).

A record is yielded as soon as its line ending has been read, a line feed or a complete CRLF, even while the stream stays open. A record is held back only while its end is not yet known: inside a quoted field, or before its line ending has arrived, since more of its last field could follow; and when the input read so far ends with a carriage return, which could be the first half of a CRLF. The end of the stream completes a record held back for either reason. A malformed tail is retried as later segments arrive and only surfaces as a DelimitedFormatException once the end of the stream confirms it.

Every DelimitedFormatException reports its line and byte offset counted from the start of the stream, as Deserialize<TRecord>(Stream, DelimitedSerializerOptions?) does, whichever read held the error; an offset greater than MaxValue is reported as null.

The arguments, the dialect and TRecord are validated when the method is called, so an ArgumentNullException, an ArgumentException, or a DelimitedSerializationException for an unusable record type is thrown before the sequence is enumerated. A DelimitedFormatException, and a DelimitedSerializationException for a record that cannot be mapped, are thrown while it is enumerated.

Exceptions

ArgumentNullException

Thrown when source is null.

DelimitedFormatException

Thrown when the content is not valid delimited data.

DelimitedSerializationException

Thrown when TRecord is not a record type, has no public parameterless constructor or has a member whose type is not a scalar, or when a record cannot be mapped.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the reader (see DelimitedReaderOptions).

Deserialize<TRecord>(Stream, DelimitedSerializerOptions?)

Deserializes the delimited content of the supplied stream into a list of records.

[RequiresUnreferencedCode("Reflection-based delimited serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based delimited serialization may require runtime code generation.")]
public static List<TRecord> Deserialize<TRecord>(Stream source, DelimitedSerializerOptions? options = null)

Parameters

source Stream

The source stream.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Returns

List<TRecord>

The list of deserialized records.

Type Parameters

TRecord

The record type.

Exceptions

ArgumentNullException

Thrown when source is null.

DelimitedFormatException

Thrown when the content is not valid delimited data.

DelimitedSerializationException

Thrown when TRecord is not a record type, has no public parameterless constructor or has a member whose type is not a scalar, or when a record cannot be mapped.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the reader (see DelimitedReaderOptions).

Deserialize<TRecord>(Stream, IDelimitedRecordFactory<TRecord>, DelimitedSerializerOptions?)

Deserializes the delimited content of the supplied stream into a list of records using a record factory instead of reflection.

public static List<TRecord> Deserialize<TRecord>(Stream source, IDelimitedRecordFactory<TRecord> factory, DelimitedSerializerOptions? options = null)

Parameters

source Stream

The source stream.

factory IDelimitedRecordFactory<TRecord>

The record factory that binds decoded rows.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Returns

List<TRecord>

The list of deserialized records.

Type Parameters

TRecord

The record type.

Exceptions

ArgumentNullException

Thrown when source or factory is null.

DelimitedFormatException

Thrown when the content is not valid delimited data.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the reader (see DelimitedReaderOptions).

DelimitedSerializationException

Thrown when the factory cannot convert a field value; the conversion error is the inner exception.

Deserialize<TRecord>(ReadOnlySpan<byte>, DelimitedSerializerOptions?)

Deserializes the specified UTF-8 delimited bytes into a list of records.

[RequiresUnreferencedCode("Reflection-based delimited serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based delimited serialization may require runtime code generation.")]
public static List<TRecord> Deserialize<TRecord>(ReadOnlySpan<byte> utf8Delimited, DelimitedSerializerOptions? options = null)

Parameters

utf8Delimited ReadOnlySpan<byte>

The delimited source bytes.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Returns

List<TRecord>

The list of deserialized records.

Type Parameters

TRecord

The record type.

Exceptions

DelimitedFormatException

Thrown when the bytes are not valid delimited data.

DelimitedSerializationException

Thrown when TRecord is not a record type, has no public parameterless constructor or has a member whose type is not a scalar, or when a record cannot be mapped.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the reader (see DelimitedReaderOptions).

Deserialize<TRecord>(ReadOnlySpan<byte>, IDelimitedRecordFactory<TRecord>, DelimitedSerializerOptions?)

Deserializes the specified UTF-8 delimited bytes into a list of records using a record factory instead of reflection.

public static List<TRecord> Deserialize<TRecord>(ReadOnlySpan<byte> utf8Delimited, IDelimitedRecordFactory<TRecord> factory, DelimitedSerializerOptions? options = null)

Parameters

utf8Delimited ReadOnlySpan<byte>

The delimited source bytes.

factory IDelimitedRecordFactory<TRecord>

The record factory that binds decoded rows.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Returns

List<TRecord>

The list of deserialized records.

Type Parameters

TRecord

The record type.

Exceptions

ArgumentNullException

Thrown when factory is null.

DelimitedFormatException

Thrown when the bytes are not valid delimited data.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the reader (see DelimitedReaderOptions).

DelimitedSerializationException

Thrown when the factory cannot convert a field value; the conversion error is the inner exception.

Deserialize<TRecord>(string, DelimitedSerializerOptions?)

Deserializes the specified delimited text into a list of records.

[RequiresUnreferencedCode("Reflection-based delimited serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based delimited serialization may require runtime code generation.")]
public static List<TRecord> Deserialize<TRecord>(string text, DelimitedSerializerOptions? options = null)

Parameters

text string

The delimited source text.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Returns

List<TRecord>

The list of deserialized records.

Type Parameters

TRecord

The record type.

Exceptions

ArgumentNullException

Thrown when text is null.

DelimitedFormatException

Thrown when the text is not valid delimited data.

DelimitedSerializationException

Thrown when TRecord is not a record type, has no public parameterless constructor or has a member whose type is not a scalar, or when a record cannot be mapped.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the reader (see DelimitedReaderOptions).

Deserialize<TRecord>(string, IDelimitedRecordFactory<TRecord>, DelimitedSerializerOptions?)

Deserializes the specified delimited text into a list of records using a record factory instead of reflection.

public static List<TRecord> Deserialize<TRecord>(string text, IDelimitedRecordFactory<TRecord> factory, DelimitedSerializerOptions? options = null)

Parameters

text string

The delimited source text.

factory IDelimitedRecordFactory<TRecord>

The record factory that binds decoded rows.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Returns

List<TRecord>

The list of deserialized records.

Type Parameters

TRecord

The record type.

Exceptions

ArgumentNullException

Thrown when text or factory is null.

DelimitedFormatException

Thrown when the text is not valid delimited data.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the reader (see DelimitedReaderOptions).

DelimitedSerializationException

Thrown when the factory cannot convert a field value; the conversion error is the inner exception.

SerializeAsync<TRecord>(Stream, IAsyncEnumerable<TRecord>, DelimitedSerializerOptions?, CancellationToken)

Asynchronously serializes an asynchronous sequence of records as delimited text to the supplied stream, writing incrementally as records arrive.

[RequiresUnreferencedCode("Reflection-based delimited serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based delimited serialization may require runtime code generation.")]
public static ValueTask SerializeAsync<TRecord>(Stream destination, IAsyncEnumerable<TRecord> records, DelimitedSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

destination Stream

The destination stream.

records IAsyncEnumerable<TRecord>

The asynchronous record sequence.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that cancels the operation.

Returns

ValueTask

A task that completes when all records have been written.

Type Parameters

TRecord

The record type.

Remarks

The sequence is never materialized: each record is encoded as it is produced and flushed to destination in bounded batches, so memory use is independent of the sequence length. The header row (for a POCO record type, unless NoHeader is set) is emitted before the first record, or on its own when the sequence has no records.

Exceptions

ArgumentNullException

Thrown when destination or records is null.

DelimitedSerializationException

Thrown when TRecord is not a record type but a scalar or a collection, or when a member of it is not a scalar, or one declared as object holds a value that is not.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the writer (see DelimitedWriterOptions).

SerializeAsync<T>(Stream, T, DelimitedSerializerOptions?, CancellationToken)

Asynchronously serializes the specified collection of records as delimited text to the supplied stream.

[RequiresUnreferencedCode("Reflection-based delimited serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based delimited serialization may require runtime code generation.")]
public static ValueTask SerializeAsync<T>(Stream destination, T value, DelimitedSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

destination Stream

The destination stream.

value T

The records to serialize.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that cancels the final stream write.

Returns

ValueTask

A task that completes when the delimited text has been written.

Type Parameters

T

The collection type.

Exceptions

ArgumentNullException

Thrown when destination is null.

DelimitedSerializationException

Thrown when T is not a collection of records, such as a string, or its element type is not a record type but a scalar or a collection, or when a member of the record type is not a scalar, or one declared as object holds a value that is not.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the writer (see DelimitedWriterOptions).

Serialize<TRecord>(IBufferWriter<byte>, IEnumerable<TRecord>, IDelimitedRecordFactory<TRecord>, DelimitedSerializerOptions?)

Serializes the specified records as delimited text to the supplied buffer writer using a record factory instead of reflection.

public static void Serialize<TRecord>(IBufferWriter<byte> destination, IEnumerable<TRecord> records, IDelimitedRecordFactory<TRecord> factory, DelimitedSerializerOptions? options = null)

Parameters

destination IBufferWriter<byte>

The buffer writer that receives the delimited bytes.

records IEnumerable<TRecord>

The records to serialize.

factory IDelimitedRecordFactory<TRecord>

The record factory that supplies headers and field values.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Type Parameters

TRecord

The record type.

Exceptions

ArgumentNullException

Thrown when destination, records, or factory is null.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the writer (see DelimitedWriterOptions).

Serialize<T>(IBufferWriter<byte>, T, DelimitedSerializerOptions?)

Serializes the specified collection of records as delimited text to the supplied buffer writer.

[RequiresUnreferencedCode("Reflection-based delimited serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based delimited serialization may require runtime code generation.")]
public static void Serialize<T>(IBufferWriter<byte> destination, T value, DelimitedSerializerOptions? options = null)

Parameters

destination IBufferWriter<byte>

The buffer writer that receives the delimited bytes.

value T

The records to serialize.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Type Parameters

T

The collection type.

Exceptions

ArgumentNullException

Thrown when destination is null.

DelimitedSerializationException

Thrown when T is not a collection of records, such as a string, or its element type is not a record type but a scalar or a collection, or when a member of the record type is not a scalar, or one declared as object holds a value that is not.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the writer (see DelimitedWriterOptions).

Serialize<TRecord>(IEnumerable<TRecord>, IDelimitedRecordFactory<TRecord>, DelimitedSerializerOptions?)

Serializes the specified records to delimited text using a record factory instead of reflection.

public static string Serialize<TRecord>(IEnumerable<TRecord> records, IDelimitedRecordFactory<TRecord> factory, DelimitedSerializerOptions? options = null)

Parameters

records IEnumerable<TRecord>

The records to serialize.

factory IDelimitedRecordFactory<TRecord>

The record factory that supplies headers and field values.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Returns

string

The delimited text.

Type Parameters

TRecord

The record type.

Exceptions

ArgumentNullException

Thrown when records or factory is null.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the writer (see DelimitedWriterOptions).

Serialize<T>(T, DelimitedSerializerOptions?)

Serializes the specified collection of records to delimited text.

[RequiresUnreferencedCode("Reflection-based delimited serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based delimited serialization may require runtime code generation.")]
public static string Serialize<T>(T value, DelimitedSerializerOptions? options = null)

Parameters

value T

The records to serialize.

options DelimitedSerializerOptions

The serializer options, or null to use the defaults.

Returns

string

The delimited text.

Type Parameters

T

The collection type.

Exceptions

DelimitedSerializationException

Thrown when T is not a collection of records, such as a string, or its element type is not a record type but a scalar or a collection, or when a member of the record type is not a scalar, or one declared as object holds a value that is not.

ArgumentException

Thrown when the delimiter, quote or comment character of options cannot be used by the writer (see DelimitedWriterOptions).

Applies to

ProductVersions
.NET8, 10