DelimitedSerializer Class

Definition

Namespace

Bodu.Text.Delimited

Assembly

Bodu.Text.Delimited.dll

Package

Bodu.Text.Delimited 1.0.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

object

DelimitedSerializer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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 honour PropertyNamingPolicy and the PropertyNameAttribute family.

The buffered stream overloads mirror the sibling quartet libraries. The DeserializeAsyncEnumerableAsync<TRecord>(Stream, DelimitedSerializerOptions?, CancellationToken) 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 observed.

[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 record that ends exactly at the current buffer boundary is held back until the next segment (or the end of the stream) proves it complete, because more fields could still follow. A malformed tail is retried as later segments arrive and only surfaces as a DelimitedFormatException once the end of the stream confirms it.

Exceptions

ArgumentNullException

Thrown when source is null.

DelimitedFormatException

Thrown when the content is not valid delimited data.

DelimitedSerializationException

Thrown when a record cannot be mapped.

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 a record cannot be mapped.

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.

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 a record cannot be mapped.

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.

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 a record cannot be mapped.

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.

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.

Exceptions

ArgumentNullException

Thrown when destination or records is null.

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.

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.

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.

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.

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.

Applies to

Product	Versions
.NET	8, 10