DelimitedSerializer Class
Definition
- Assembly
- Bodu.Text.Delimited.dll
- Package
- Bodu.Text.Delimited 1.3.0
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
sourceStreamThe source stream.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
cancellationTokenCancellationTokenA token that cancels the operation.
Returns
- IAsyncEnumerable<TRecord>
An asynchronous sequence of records.
Type Parameters
TRecordThe 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
sourceis null.- DelimitedFormatException
Thrown when the content is not valid delimited data.
- DelimitedSerializationException
Thrown when
TRecordis 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
optionscannot 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
sourceStreamThe source stream.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- List<TRecord>
The list of deserialized records.
Type Parameters
TRecordThe record type.
Exceptions
- ArgumentNullException
Thrown when
sourceis null.- DelimitedFormatException
Thrown when the content is not valid delimited data.
- DelimitedSerializationException
Thrown when
TRecordis 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
optionscannot 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
sourceStreamThe source stream.
factoryIDelimitedRecordFactory<TRecord>The record factory that binds decoded rows.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- List<TRecord>
The list of deserialized records.
Type Parameters
TRecordThe record type.
Exceptions
- ArgumentNullException
Thrown when
sourceorfactoryis null.- DelimitedFormatException
Thrown when the content is not valid delimited data.
- ArgumentException
Thrown when the delimiter, quote or comment character of
optionscannot 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
utf8DelimitedReadOnlySpan<byte>The delimited source bytes.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- List<TRecord>
The list of deserialized records.
Type Parameters
TRecordThe record type.
Exceptions
- DelimitedFormatException
Thrown when the bytes are not valid delimited data.
- DelimitedSerializationException
Thrown when
TRecordis 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
optionscannot 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
utf8DelimitedReadOnlySpan<byte>The delimited source bytes.
factoryIDelimitedRecordFactory<TRecord>The record factory that binds decoded rows.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- List<TRecord>
The list of deserialized records.
Type Parameters
TRecordThe record type.
Exceptions
- ArgumentNullException
Thrown when
factoryis null.- DelimitedFormatException
Thrown when the bytes are not valid delimited data.
- ArgumentException
Thrown when the delimiter, quote or comment character of
optionscannot 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
textstringThe delimited source text.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- List<TRecord>
The list of deserialized records.
Type Parameters
TRecordThe record type.
Exceptions
- ArgumentNullException
Thrown when
textis null.- DelimitedFormatException
Thrown when the text is not valid delimited data.
- DelimitedSerializationException
Thrown when
TRecordis 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
optionscannot 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
textstringThe delimited source text.
factoryIDelimitedRecordFactory<TRecord>The record factory that binds decoded rows.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- List<TRecord>
The list of deserialized records.
Type Parameters
TRecordThe record type.
Exceptions
- ArgumentNullException
Thrown when
textorfactoryis null.- DelimitedFormatException
Thrown when the text is not valid delimited data.
- ArgumentException
Thrown when the delimiter, quote or comment character of
optionscannot 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
destinationStreamThe destination stream.
recordsIAsyncEnumerable<TRecord>The asynchronous record sequence.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
cancellationTokenCancellationTokenA token that cancels the operation.
Returns
- ValueTask
A task that completes when all records have been written.
Type Parameters
TRecordThe 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
destinationorrecordsis null.- DelimitedSerializationException
Thrown when
TRecordis 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
optionscannot 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
destinationStreamThe destination stream.
valueTThe records to serialize.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
cancellationTokenCancellationTokenA token that cancels the final stream write.
Returns
- ValueTask
A task that completes when the delimited text has been written.
Type Parameters
TThe collection type.
Exceptions
- ArgumentNullException
Thrown when
destinationis null.- DelimitedSerializationException
Thrown when
Tis 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
optionscannot 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
destinationIBufferWriter<byte>The buffer writer that receives the delimited bytes.
recordsIEnumerable<TRecord>The records to serialize.
factoryIDelimitedRecordFactory<TRecord>The record factory that supplies headers and field values.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Type Parameters
TRecordThe record type.
Exceptions
- ArgumentNullException
Thrown when
destination,records, orfactoryis null.- ArgumentException
Thrown when the delimiter, quote or comment character of
optionscannot 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
destinationIBufferWriter<byte>The buffer writer that receives the delimited bytes.
valueTThe records to serialize.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Type Parameters
TThe collection type.
Exceptions
- ArgumentNullException
Thrown when
destinationis null.- DelimitedSerializationException
Thrown when
Tis 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
optionscannot 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
recordsIEnumerable<TRecord>The records to serialize.
factoryIDelimitedRecordFactory<TRecord>The record factory that supplies headers and field values.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- string
The delimited text.
Type Parameters
TRecordThe record type.
Exceptions
- ArgumentNullException
Thrown when
recordsorfactoryis null.- ArgumentException
Thrown when the delimiter, quote or comment character of
optionscannot 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
valueTThe records to serialize.
optionsDelimitedSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- string
The delimited text.
Type Parameters
TThe collection type.
Exceptions
- DelimitedSerializationException
Thrown when
Tis 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
optionscannot be used by the writer (see DelimitedWriterOptions).
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |