CsvWriter class · CsvHelper

public sealed class CsvWriter : IDisposable, IAsyncDisposable

Namespace: CsvHelper
Assembly: CsvHelper.dll
Implements: IDisposable, IAsyncDisposable
Builds: net10.0 netstandard2.1 netstandard2.0 net47
Source: CsvWriter.cs

Remarks

Fields are written into an internal buffer; I/O only happens in EndRecord (when the buffer is mostly full), Flush and their async counterparts, so async callers never block.

A writer is not thread-safe: use it from one thread at a time, and finish each async call before starting the next. Nothing checks this; fields from two threads end up mixed in the output. To write records produced on several threads, write them from one thread, or lock around each whole record, from its first field to EndRecord. To format records on several threads, use ParallelWriteRecords<T>(IEnumerable<T>, int) or ParallelWrite. The options and the record writers do not change, so they can be shared between threads.

Properties

FieldCount

Added in v34.0.0

public int FieldCount { get; }

The number of fields written to the current record so far.

Property value

int

Options

Added in v34.0.0

public CsvWriterOptions Options { get; }

The options this writer was created with.

Property value

CsvWriterOptions

RecordCount

Added in v34.0.0

public long RecordCount { get; }

The number of complete records written so far (the header counts as a record).

Property value

long

Methods

Create(Stream, CsvWriterOptions, bool)

Added in v34.0.0static

public static CsvWriter Create(Stream stream, CsvWriterOptions? options = null, bool leaveOpen = false)

Creates a writer that writes UTF-8 to a stream.

Parameters

streamStream: The destination, written from its current position.
optionsCsvWriterOptions?: The options, or null for CsvWriterOptions.Default.
leaveOpenbool: Whether stream stays open when the writer is disposed.

Returns

A writer positioned at the start of the first record.

Exceptions

ArgumentNullException: stream is null.
ArgumentException: options are not valid: a CsvWriterOptions.Separator that is not ASCII or is CR, LF or (in Rfc4180 mode) the quote, an CsvWriterOptions.Escape that cannot be used, or missing or non-positive CsvWriterOptions.FieldWidths in FixedWidth mode.
ArgumentOutOfRangeException: CsvWriterOptions.BufferSize is less than 256.

Create(TextWriter, CsvWriterOptions, bool)

Added in v34.0.0static

public static CsvWriter Create(TextWriter textWriter, CsvWriterOptions? options = null, bool leaveOpen = false)

Creates a writer that writes to a TextWriter.

Parameters

textWriterTextWriter: The destination. It gets UTF-16 text, which it encodes itself; CsvWriterOptions.WriteByteOrderMark does not apply to it.
optionsCsvWriterOptions?: The options, or null for CsvWriterOptions.Default.
leaveOpenbool: Whether textWriter stays open when the writer is disposed.

Returns

A writer positioned at the start of the first record.

Exceptions

ArgumentNullException: textWriter is null.
ArgumentException: options are not valid: a CsvWriterOptions.Separator that is not ASCII or is CR, LF or (in Rfc4180 mode) the quote, an CsvWriterOptions.Escape that cannot be used, or missing or non-positive CsvWriterOptions.FieldWidths in FixedWidth mode.
ArgumentOutOfRangeException: CsvWriterOptions.BufferSize is less than 256.

Dispose()

public void Dispose()

Ends an unfinished record (without checking its field count), writes the buffer to the destination, flushes it and disposes it, unless the writer was created with leaveOpen. Calling it again does nothing.

DisposeAsync()

Added in v14.0.0

public ValueTask DisposeAsync()

Ends an unfinished record (without checking its field count), asynchronously writes the buffer to the destination, flushes it and disposes it, unless the writer was created with leaveOpen. Calling it again does nothing.

Returns

A task that completes when the destination has been flushed and, unless left open, disposed.

EndRecord()

Added in v34.0.0

public void EndRecord()

Ends the current record with CRLF (CsvWriterOptions.NewLine). In Rfc4180 mode, a record whose only field is empty is written as "", so it does not read as an empty line. Writes the buffer to the destination when it is mostly full.

Exceptions

InvalidOperationException: The record has no fields, or its field count differs from the first record, or (in FixedWidth mode with a CsvWriterOptions.CommentPrefix) its first field starts with the comment prefix. The record is discarded.

EndRecordAsync(CancellationToken)

Added in v34.0.0

public ValueTask EndRecordAsync(CancellationToken cancellationToken = default)

Ends the current record, flushing asynchronously when the buffer is mostly full. See EndRecord.

Parameters

cancellationTokenCancellationToken: Cancels writing to the destination.

Returns

A task that completes when the record is in the buffer and, if the buffer was mostly full, written out.

Exceptions

InvalidOperationException: The record has no fields, or its field count differs from the first record, or (in FixedWidth mode with a CsvWriterOptions.CommentPrefix) its first field starts with the comment prefix. The record is discarded.
OperationCanceledException: cancellationToken was canceled.

Flush()

public void Flush()

Writes buffered records to the destination and flushes it. The fields of an unfinished record are written too.

Exceptions

ObjectDisposedException: The writer has been disposed.

FlushAsync(CancellationToken)

Added in v34.0.0

public ValueTask FlushAsync(CancellationToken cancellationToken = default)

Asynchronously writes buffered records to the destination and flushes it. See Flush.

Parameters

cancellationTokenCancellationToken: Cancels writing to the destination.

Returns

A task that completes when the destination has been flushed.

Exceptions

ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

ParallelWrite<T>(IEnumerable<T>, Action<CsvWriter, T>, int)

Added in v34.0.0

public void ParallelWrite<T>(IEnumerable<T> items, Action<CsvWriter, T> write, int maxDegreeOfParallelism = -1)

Writes the records of each item with write, called on several threads, and writes them to the destination in input order: the output of a foreach loop that calls write with this writer.

Type parameters

T: The type of the items.

Parameters

itemsIEnumerable<T>: The items, enumerated once, on this thread; the workers read an array or a List<T> in place.
writeAction<CsvWriter, T>: Writes the records of an item to the writer it gets.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.

Exceptions

ArgumentNullException: items or write is null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: A record is not valid (see EndRecord), the callback left a record unfinished, or this writer is the one a callback got. The record is discarded; the records before it are written, and none after it.
ObjectDisposedException: The writer has been disposed.

Remarks

This thread enumerates items and writes to the destination, while workers call write for batches of items. The callback gets the worker's writer (or this writer, for the items written on this thread) and writes whole records of the item on it: fields and EndRecord, WriteRecord<T>(T) and the like, as many records as the item needs, or none. A record that it leaves unfinished throws InvalidOperationException. Do not flush or dispose that writer, or start a parallel write with it.

Calls run concurrently, so anything shared that the callback changes must be thread-safe, and so must the converters and CsvWriterOptions.ShouldQuote. No header is written: write it first, with WriteHeader(params ReadOnlySpan<string>) or WriteHeader<T>(). When records must have as many fields as the first (CsvWriterOptions.ValidateFieldCount) and none has been written, the items up to the first record are written on this thread before the workers start, and so are items that fit in one batch.

The callback's writer numbers records as if every item wrote one: at the start of an item, its RecordCount (the record index that CsvWriterOptions.ShouldQuote gets, and the record number in exception messages) is the RecordCount of this writer before the call plus the index of the item. After the call, RecordCount counts every record written. An exception, from the enumeration or from the callback, is thrown after the records of the items before it are written. Do not use this writer otherwise until the call returns.

ParallelWriteAsync<T>(IAsyncEnumerable<T>, Action<CsvWriter, T>, int, CancellationToken)

Added in v34.0.0

public ValueTask ParallelWriteAsync<T>(IAsyncEnumerable<T> items, Action<CsvWriter, T> write, int maxDegreeOfParallelism = -1, CancellationToken cancellationToken = default)

Writes the records of each item of an asynchronous sequence with write as ParallelWrite does, enumerating it and writing to the destination asynchronously.

Type parameters

T: The type of the items.

Parameters

itemsIAsyncEnumerable<T>: The items, enumerated once, by this call.
writeAction<CsvWriter, T>: Writes the records of an item to the writer it gets; called on several threads at once.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.
cancellationTokenCancellationToken: Cancels the enumeration of items, waiting for the workers and writing to the destination.

Returns

A task that completes when every record has been written to the destination.

Exceptions

ArgumentNullException: items or write is null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: A record is not valid (see EndRecord), the callback left a record unfinished, or this writer is the one a callback got. The record is discarded; the records before it are written, and none after it.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

ParallelWriteAsync<T>(IEnumerable<T>, Action<CsvWriter, T>, int, CancellationToken)

Added in v34.0.0

public ValueTask ParallelWriteAsync<T>(IEnumerable<T> items, Action<CsvWriter, T> write, int maxDegreeOfParallelism = -1, CancellationToken cancellationToken = default)

Writes the records of each item with write as ParallelWrite does, writing to the destination asynchronously.

Type parameters

T: The type of the items.

Parameters

itemsIEnumerable<T>: The items, enumerated once, on this thread; the workers read an array or a List<T> in place.
writeAction<CsvWriter, T>: Writes the records of an item to the writer it gets; called on several threads at once.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.
cancellationTokenCancellationToken: Cancels waiting for the workers and writing to the destination.

Returns

A task that completes when every record has been written to the destination.

Exceptions

ArgumentNullException: items or write is null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: A record is not valid (see EndRecord), the callback left a record unfinished, or this writer is the one a callback got. The record is discarded; the records before it are written, and none after it.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

ParallelWriteRecords<T>(IEnumerable<T>, int)

Added in v34.0.0

public void ParallelWriteRecords<T>(IEnumerable<T> records, int maxDegreeOfParallelism = -1)

Writes records as WriteRecords<T>(IEnumerable<T>) does, formatting them on several threads: the output is the same, in the same order.

Type parameters

T: The CsvRecordAttribute type, or a type of dynamic records (see WriteRecords<T>(IEnumerable<T>)).

Parameters

recordsIEnumerable<T>: The records, enumerated once, on this thread; the workers read an array or a List<T> in place.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.

Exceptions

ArgumentNullException: records is null.
ArgumentException: records contains null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, a record is not valid (see EndRecord), or this writer is the one a ParallelWrite callback got. An invalid record is discarded; the records before it are written, and none after it.
FormatException: A member's format is not valid for its type.
ObjectDisposedException: The writer has been disposed.

Remarks

This thread enumerates records and writes to the destination, while workers format batches of records, each with a writer of its own. The header, and the first record when it fixes the field count (CsvWriterOptions.ValidateFieldCount) or the columns of dynamic records, are written on this thread before the workers start, and so are records that fit in one batch.

The record writer, the converters and CsvWriterOptions.ShouldQuote are called on several threads at once, so they must be thread-safe; generated record writers are. What this writer has buffered is written to the destination before the first batch, and each batch as soon as the batches before it are, without flushing the destination. An exception, from the enumeration or from a record, is thrown after the records before it are written. Do not use this writer otherwise until the call returns.

ParallelWriteRecords<T>(IEnumerable<T>, CsvRecordWriter<T>, int)

Added in v34.0.0

public void ParallelWriteRecords<T>(IEnumerable<T> records, CsvRecordWriter<T> recordWriter, int maxDegreeOfParallelism = -1)

Writes records with recordWriter, as WriteRecords<T>(IEnumerable<T>, CsvRecordWriter<T>) does, formatting them on several threads: the output is the same, in the same order. See ParallelWriteRecords<T>(IEnumerable<T>, int).

Type parameters

T: The type of the records.

Parameters

recordsIEnumerable<T>: The records, enumerated once, on this thread; the workers read an array or a List<T> in place.
recordWriterCsvRecordWriter<T>: Writes the header and the fields of each record.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.

Exceptions

ArgumentNullException: records or recordWriter is null.
ArgumentException: records contains null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: A record is not valid (see EndRecord), or this writer is the one a ParallelWrite callback got. An invalid record is discarded; the records before it are written, and none after it.
ObjectDisposedException: The writer has been disposed.

Remarks

The workers share recordWriter, so it must be thread-safe: one that keeps no state between calls of CsvRecordWriter<T>.Write is.

ParallelWriteRecordsAsync<T>(IAsyncEnumerable<T>, int, CancellationToken)

Added in v34.0.0

public ValueTask ParallelWriteRecordsAsync<T>(IAsyncEnumerable<T> records, int maxDegreeOfParallelism = -1, CancellationToken cancellationToken = default)

Writes an asynchronous sequence of records as ParallelWriteRecords<T>(IEnumerable<T>, int) does, enumerating it and writing to the destination asynchronously.

Type parameters

T: The CsvRecordAttribute type, or a type of dynamic records (see WriteRecords<T>(IEnumerable<T>)).

Parameters

recordsIAsyncEnumerable<T>: The records, enumerated once, by this call.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.
cancellationTokenCancellationToken: Cancels the enumeration of records, waiting for the workers and writing to the destination.

Returns

A task that completes when every record has been written to the destination.

Exceptions

ArgumentNullException: records is null.
ArgumentException: records contains null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, a record is not valid (see EndRecord), or this writer is the one a ParallelWrite callback got. An invalid record is discarded; the records before it are written, and none after it.
FormatException: A member's format is not valid for its type.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

ParallelWriteRecordsAsync<T>(IEnumerable<T>, int, CancellationToken)

Added in v34.0.0

public ValueTask ParallelWriteRecordsAsync<T>(IEnumerable<T> records, int maxDegreeOfParallelism = -1, CancellationToken cancellationToken = default)

Writes records as ParallelWriteRecords<T>(IEnumerable<T>, int) does, writing to the destination asynchronously.

Type parameters

T: The CsvRecordAttribute type, or a type of dynamic records (see WriteRecords<T>(IEnumerable<T>)).

Parameters

recordsIEnumerable<T>: The records, enumerated once, on this thread; the workers read an array or a List<T> in place.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.
cancellationTokenCancellationToken: Cancels waiting for the workers and writing to the destination.

Returns

A task that completes when every record has been written to the destination.

Exceptions

ArgumentNullException: records is null.
ArgumentException: records contains null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, a record is not valid (see EndRecord), or this writer is the one a ParallelWrite callback got. An invalid record is discarded; the records before it are written, and none after it.
FormatException: A member's format is not valid for its type.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

ParallelWriteRecordsAsync<T>(IAsyncEnumerable<T>, CsvRecordWriter<T>, int, CancellationToken)

Added in v34.0.0

public ValueTask ParallelWriteRecordsAsync<T>(IAsyncEnumerable<T> records, CsvRecordWriter<T> recordWriter, int maxDegreeOfParallelism = -1, CancellationToken cancellationToken = default)

Writes an asynchronous sequence of records with recordWriter as ParallelWriteRecords<T>(IEnumerable<T>, CsvRecordWriter<T>, int) does, enumerating it and writing to the destination asynchronously.

Type parameters

T: The type of the records.

Parameters

recordsIAsyncEnumerable<T>: The records, enumerated once, by this call.
recordWriterCsvRecordWriter<T>: Writes the header and the fields of each record; the workers share it.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.
cancellationTokenCancellationToken: Cancels the enumeration of records, waiting for the workers and writing to the destination.

Returns

A task that completes when every record has been written to the destination.

Exceptions

ArgumentNullException: records or recordWriter is null.
ArgumentException: records contains null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: A record is not valid (see EndRecord), or this writer is the one a ParallelWrite callback got. An invalid record is discarded; the records before it are written, and none after it.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

ParallelWriteRecordsAsync<T>(IEnumerable<T>, CsvRecordWriter<T>, int, CancellationToken)

Added in v34.0.0

public ValueTask ParallelWriteRecordsAsync<T>(IEnumerable<T> records, CsvRecordWriter<T> recordWriter, int maxDegreeOfParallelism = -1, CancellationToken cancellationToken = default)

Writes records with recordWriter as ParallelWriteRecords<T>(IEnumerable<T>, CsvRecordWriter<T>, int) does, writing to the destination asynchronously.

Type parameters

T: The type of the records.

Parameters

recordsIEnumerable<T>: The records, enumerated once, on this thread; the workers read an array or a List<T> in place.
recordWriterCsvRecordWriter<T>: Writes the header and the fields of each record; the workers share it.
maxDegreeOfParallelismint: The number of worker threads, or -1 for one per processor.
cancellationTokenCancellationToken: Cancels waiting for the workers and writing to the destination.

Returns

A task that completes when every record has been written to the destination.

Exceptions

ArgumentNullException: records or recordWriter is null.
ArgumentException: records contains null.
ArgumentOutOfRangeException: maxDegreeOfParallelism is 0 or less than -1.
InvalidOperationException: A record is not valid (see EndRecord), or this writer is the one a ParallelWrite callback got. An invalid record is discarded; the records before it are written, and none after it.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

ToFile(string, CsvWriterOptions, FileOptions)

Added in v34.0.0static

public static CsvWriter ToFile(string path, CsvWriterOptions? options = null, FileOptions fileOptions = FileOptions.None)

Creates (or overwrites) a file, which other processes can read while it is written. The writer closes the file when it is disposed. See Create(Stream, CsvWriterOptions, bool).

Parameters

pathstring: The path of the file.
optionsCsvWriterOptions?: The options, or null for CsvWriterOptions.Default.
fileOptionsFileOptions: How the file is opened.

Returns

A writer positioned at the start of the file.

Exceptions

ArgumentException: path is empty, or options are not valid (see Create(Stream, CsvWriterOptions, bool)).
ArgumentNullException: path is null.
ArgumentOutOfRangeException: CsvWriterOptions.BufferSize is less than 256.
DirectoryNotFoundException: The directory of the file does not exist.
UnauthorizedAccessException: The file cannot be written with the caller's permissions.
IOException: The file cannot be created, for example because another process has it open.

WriteComment(ReadOnlySpan<char>)

Added in v34.0.0

public void WriteComment(ReadOnlySpan<char> text)

Writes a comment line: CsvWriterOptions.CommentPrefix, the text and the line ending. A text with line breaks becomes several comment lines, one per line. Comments are not records: they do not count in RecordCount or for the field count of records.

Parameters

textReadOnlySpan<char>: The text of the comment, written as it is (without quotes or escapes).

Exceptions

InvalidOperationException: CsvWriterOptions.CommentPrefix is not set, or fields of a record have been written and the record has not ended.
ObjectDisposedException: The writer has been disposed.

WriteComment(string)

public void WriteComment(string? text)

Writes a comment line: CsvWriterOptions.CommentPrefix, the text and the line ending. A text with line breaks becomes several comment lines, one per line. Comments are not records: they do not count in RecordCount or for the field count of records.

Parameters

textstring?: The text of the comment, written as it is (without quotes or escapes); null writes the prefix alone.

Exceptions

InvalidOperationException: CsvWriterOptions.CommentPrefix is not set, or fields of a record have been written and the record has not ended.
ObjectDisposedException: The writer has been disposed.

WriteField(ReadOnlySpan<byte>)

Added in v34.0.0

public void WriteField(ReadOnlySpan<byte> utf8)

Writes a field from UTF-8 bytes.

Parameters

utf8ReadOnlySpan<byte>: The value, copied as is (it is not validated). It is quoted when it contains the separator, a quote, CR or LF (or always, with CsvQuoting.Always), or escaped or padded as CsvWriterOptions.Mode says.

Exceptions

ObjectDisposedException: The writer has been disposed.

WriteField(ReadOnlySpan<char>)

Added in v34.0.0

public void WriteField(ReadOnlySpan<char> value)

Writes a field from UTF-16 text.

Parameters

valueReadOnlySpan<char>: The value. It is quoted when it contains the separator, a quote, CR or LF (or always, with CsvQuoting.Always), or escaped or padded as CsvWriterOptions.Mode says; invalid UTF-16 is replaced with U+FFFD.

Exceptions

ObjectDisposedException: The writer has been disposed.

WriteField(bool)

Added in v34.0.0

public void WriteField(bool value)

Writes CsvWriterOptions.TrueValue or CsvWriterOptions.FalseValue: True or False by default.

Parameters

valuebool: The value.

Exceptions

ObjectDisposedException: The writer has been disposed.

WriteField(object)

Added in v34.0.0

public void WriteField(object? value)

Writes any value: strings and UTF-8 formattable values directly, other IFormattable values with the configured format provider, anything else via object.ToString.

Parameters

valueobject?: The value, or null for CsvWriterOptions.NullValue (an empty field by default).

Exceptions

ObjectDisposedException: The writer has been disposed.

WriteField(string)

public void WriteField(string? value)

Writes a field from UTF-16 text. A null string is written as CsvWriterOptions.NullValue, an empty field by default.

Parameters

valuestring?: The value. It is quoted when it contains the separator, a quote, CR or LF (or always, with CsvQuoting.Always), or escaped or padded as CsvWriterOptions.Mode says; invalid UTF-16 is replaced with U+FFFD.

Exceptions

ObjectDisposedException: The writer has been disposed.

WriteField(DateOnly, ReadOnlySpan<char>)

net10.0 onlyAdded in v34.0.0

public void WriteField(DateOnly value, ReadOnlySpan<char> format = default)

Writes a date as yyyy-MM-dd unless another format is given.

Parameters

valueDateOnly: The value.
formatReadOnlySpan<char>: The format string, or empty for "O" (yyyy-MM-dd).

Exceptions

FormatException: format is not a valid date format.
ObjectDisposedException: The writer has been disposed.

WriteField(DateTime, ReadOnlySpan<char>)

Added in v34.0.0

public void WriteField(DateTime value, ReadOnlySpan<char> format = default)

Writes a date and time in ISO 8601 round-trip format ("O") unless another format is given.

Parameters

valueDateTime: The value.
formatReadOnlySpan<char>: The format string, or empty for "O".

Exceptions

FormatException: format is not a valid date and time format.
ObjectDisposedException: The writer has been disposed.

WriteField(DateTimeOffset, ReadOnlySpan<char>)

Added in v34.0.0

public void WriteField(DateTimeOffset value, ReadOnlySpan<char> format = default)

Writes a date and time with offset in ISO 8601 round-trip format ("O") unless another format is given.

Parameters

valueDateTimeOffset: The value.
formatReadOnlySpan<char>: The format string, or empty for "O".

Exceptions

FormatException: format is not a valid date and time format.
ObjectDisposedException: The writer has been disposed.

WriteField(ReadOnlySpan<char>, CsvQuoting)

Added in v34.0.0

public void WriteField(ReadOnlySpan<char> value, CsvQuoting quoting)

Writes a field from UTF-16 text, quoted as quoting says instead of CsvWriterOptions.Quoting.

Parameters

valueReadOnlySpan<char>: The value.
quotingCsvQuoting: CsvQuoting.Always to quote the field in CsvMode.Rfc4180 mode, such as an identifier with leading zeros; CsvQuoting.WhenNeededOrWhitespace to quote it also when it starts or ends with a space or a tab; CsvQuoting.WhenNeeded to quote it as the options say. The other modes ignore it.

Exceptions

ArgumentOutOfRangeException: quoting is not a CsvQuoting value.
ObjectDisposedException: The writer has been disposed.

WriteField(string, CsvQuoting)

Added in v34.0.0

public void WriteField(string? value, CsvQuoting quoting)

Writes a field from UTF-16 text, quoted as quoting says instead of CsvWriterOptions.Quoting.

Parameters

valuestring?: The value; null is written as CsvWriterOptions.NullValue (an empty field, which CsvQuoting.Always quotes).
quotingCsvQuoting: CsvQuoting.Always to quote the field in CsvMode.Rfc4180 mode, such as an identifier with leading zeros; CsvQuoting.WhenNeededOrWhitespace to quote it also when it starts or ends with a space or a tab; CsvQuoting.WhenNeeded to quote it as the options say. The other modes ignore it.

Exceptions

ArgumentOutOfRangeException: quoting is not a CsvQuoting value.
ObjectDisposedException: The writer has been disposed.

WriteField<T>(T, ReadOnlySpan<char>)

Added in v34.0.0

net10.0

public void WriteField<T>(T value, ReadOnlySpan<char> format = default) where T : IUtf8SpanFormattable

Writes a value that formats itself as UTF-8 (numbers, Guid, ...), with the configured format provider. Without a format, double and float are written as the shortest text that round-trips, and dates and times (DateTime, DateTimeOffset, DateOnly, TimeOnly) in ISO 8601 round-trip format ("O").

Type parameters

T: The type of the value.

Parameters

valueT: The value. Its text is quoted when it contains the separator, a quote, CR or LF, or escaped or padded as CsvWriterOptions.Mode says.
formatReadOnlySpan<char>: The format string, or empty for the default format of T.

Exceptions

FormatException: format is not valid for T.
ObjectDisposedException: The writer has been disposed.

netstandard2.1, netstandard2.0, net47

public void WriteField<T>(T value, ReadOnlySpan<char> format = default) where T : IFormattable

Writes a formattable value (numbers, Guid, ...). Numbers in the invariant culture without a format are written straight to UTF-8; anything else through IFormattable.ToString. In the invariant culture without a format, double and float are written as the shortest text that round-trips, as on .NET Core 3.0 and later, and without a format, DateTime and DateTimeOffset in ISO 8601 round-trip format ("O").

Type parameters

T: The type of the value.

Parameters

valueT: The value. Its text is quoted when it contains the separator, a quote, CR or LF, or escaped or padded as CsvWriterOptions.Mode says.
formatReadOnlySpan<char>: The format string, or empty for the default format of T.

Exceptions

FormatException: format is not valid for T.
ObjectDisposedException: The writer has been disposed.

WriteField<T>(T?, ReadOnlySpan<char>)

Added in v34.0.0

net10.0

public void WriteField<T>(T? value, ReadOnlySpan<char> format = default) where T : struct, IUtf8SpanFormattable

Writes a nullable value; null is written as CsvWriterOptions.NullValue, an empty field by default. See WriteField<T>(T, ReadOnlySpan<char>).

Type parameters

T: The type of the value.

Parameters

valueT?: The value, or null.
formatReadOnlySpan<char>: The format string, or empty for the default format of T.

Exceptions

FormatException: format is not valid for T.
ObjectDisposedException: The writer has been disposed.

netstandard2.1, netstandard2.0, net47

public void WriteField<T>(T? value, ReadOnlySpan<char> format = default) where T : struct, IFormattable

Writes a nullable value; null is written as CsvWriterOptions.NullValue, an empty field by default. See WriteField<T>(T, ReadOnlySpan<char>).

Type parameters

T: The type of the value.

Parameters

valueT?: The value, or null.
formatReadOnlySpan<char>: The format string, or empty for the default format of T.

Exceptions

FormatException: format is not valid for T.
ObjectDisposedException: The writer has been disposed.

WriteField<T>(T, ReadOnlySpan<char>, IFormatProvider)

Added in v34.0.0

net10.0

public void WriteField<T>(T value, ReadOnlySpan<char> format, IFormatProvider? provider) where T : IUtf8SpanFormattable

Writes a value that formats itself as UTF-8 with the given format provider instead of CsvWriterOptions.FormatProvider, such as a culture for one column. See WriteField<T>(T, ReadOnlySpan<char>).

Type parameters

T: The type of the value.

Parameters

valueT: The value.
formatReadOnlySpan<char>: The format string, or empty for the default format of T.
providerIFormatProvider?: The format provider, or null for the writer's.

Exceptions

FormatException: format is not valid for T.
ObjectDisposedException: The writer has been disposed.

netstandard2.1, netstandard2.0, net47

public void WriteField<T>(T value, ReadOnlySpan<char> format, IFormatProvider? provider) where T : IFormattable

Writes a formattable value with the given format provider instead of CsvWriterOptions.FormatProvider, such as a culture for one column. See WriteField<T>(T, ReadOnlySpan<char>).

Type parameters

T: The type of the value.

Parameters

valueT: The value.
formatReadOnlySpan<char>: The format string, or empty for the default format of T.
providerIFormatProvider?: The format provider, or null for the writer's.

Exceptions

FormatException: format is not valid for T.
ObjectDisposedException: The writer has been disposed.

WriteHeader<T>()

public void WriteHeader<T>()

Writes the header of T, a CsvRecordAttribute type: a record with the names of its columns, which a reader maps back to its members.

Type parameters

T: The CsvRecordAttribute type.

Exceptions

InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, or the header is not a valid record (see EndRecord). The record is discarded.
ObjectDisposedException: The writer has been disposed.

WriteHeader(params ReadOnlySpan<string>)

Added in v34.0.0

public void WriteHeader(params ReadOnlySpan<string> names)

Writes a header record. It is an ordinary record: later records must have the same field count.

Parameters

namesReadOnlySpan<string>: The column names.

Exceptions

InvalidOperationException: names is empty, or the number of names differs from the first record. The record is discarded.
ObjectDisposedException: The writer has been disposed.

WriteHeader(params string[])

netstandard2.1, netstandard2.0, net47Added in v34.0.0

public void WriteHeader(params string[] names)

Writes a header record (for callers before C# 13, which cannot pass a params span).

Parameters

namesstring[]: The column names.

Exceptions

InvalidOperationException: names is empty, or the number of names differs from the first record. The record is discarded.
ObjectDisposedException: The writer has been disposed.

WriteRecord(params ReadOnlySpan<string>)

Added in v34.0.0

public void WriteRecord(params ReadOnlySpan<string?> fields)

Writes a complete record: the fields (see WriteField(string)) and then EndRecord. Fields already written to the current record come first.

Parameters

fieldsReadOnlySpan<string?>: The values of the fields; a null value is written as CsvWriterOptions.NullValue (an empty field by default).

Exceptions

InvalidOperationException: The record has no fields, or its field count differs from the first record. The record is discarded.
ObjectDisposedException: The writer has been disposed.

WriteRecord(params string[])

Added in v34.0.0

public void WriteRecord(params string?[] fields)

Writes a complete record of strings from an array (also for callers before C# 13, which cannot pass a params span). See WriteRecord(params ReadOnlySpan<string>).

Parameters

fieldsstring?[]: The values of the fields; a null value is written as CsvWriterOptions.NullValue (an empty field by default).

Exceptions

InvalidOperationException: The record has no fields, or its field count differs from the first record. The record is discarded.
ObjectDisposedException: The writer has been disposed.

WriteRecord(string)

Added in v34.0.0

public void WriteRecord(string? field)

Writes a complete record of one field (see WriteField(string)) and then EndRecord. Fields already written to the current record come first.

Parameters

fieldstring?: The value of the field; null is written as CsvWriterOptions.NullValue (an empty field by default).

Exceptions

InvalidOperationException: The field count differs from the first record. The record is discarded.
ObjectDisposedException: The writer has been disposed.

WriteRecord<T>(T)

public void WriteRecord<T>(T record)

Writes record, of a CsvRecordAttribute type, as a complete record: a field per column, formatted as its member's attributes say, then EndRecord. The record writer is created on the first call and reused while T stays the same.

Type parameters

T: The CsvRecordAttribute type.

Parameters

recordT: The record.

Exceptions

ArgumentNullException: record is null.
InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, or the record is not valid (see EndRecord). The record is discarded.
FormatException: A member's format is not valid for its type.
ObjectDisposedException: The writer has been disposed.

WriteRecordAsync(string[], CancellationToken)

Added in v34.0.0

public ValueTask WriteRecordAsync(string?[] fields, CancellationToken cancellationToken = default)

Writes a complete record and flushes asynchronously when the buffer is mostly full. See WriteRecord(params ReadOnlySpan<string>).

Parameters

fieldsstring?[]: The values of the fields; a null value is written as CsvWriterOptions.NullValue (an empty field by default).
cancellationTokenCancellationToken: Cancels writing to the destination.

Returns

A task that completes when the record is in the buffer and, if the buffer was mostly full, written out.

Exceptions

InvalidOperationException: The record has no fields, or its field count differs from the first record. The record is discarded.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

WriteRecordAsync<T>(T, CancellationToken)

Added in v34.0.0

public ValueTask WriteRecordAsync<T>(T record, CancellationToken cancellationToken = default)

Writes record as a complete record and flushes asynchronously when the buffer is mostly full. See WriteRecord<T>(T).

Type parameters

T: The CsvRecordAttribute type.

Parameters

recordT: The record.
cancellationTokenCancellationToken: Cancels writing to the destination.

Returns

A task that completes when the record is in the buffer and, if the buffer was mostly full, written out.

Exceptions

ArgumentNullException: record is null.
InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, or the record is not valid (see EndRecord). The record is discarded.
FormatException: A member's format is not valid for its type.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

WriteRecords<T>(IEnumerable<T>)

Added in v3.0.0-rc03

public void WriteRecords<T>(IEnumerable<T> records)

Writes records, of a CsvRecordAttribute type: first the header of T when nothing has been written yet (RecordCount is 0) and CsvWriterOptions.HasHeader is on, then each record.

Type parameters

T: The CsvRecordAttribute type.

Parameters

recordsIEnumerable<T>: The records, enumerated once.

Exceptions

ArgumentNullException: records is null.
ArgumentException: records contains null.
InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, or a record is not valid (see EndRecord). That record is discarded; the records before it are written.
FormatException: A member's format is not valid for its type.
ObjectDisposedException: The writer has been disposed.

WriteRecords<T>(IEnumerable<T>, CsvRecordWriter<T>)

Added in v34.0.0

public void WriteRecords<T>(IEnumerable<T> records, CsvRecordWriter<T> recordWriter)

Writes records with recordWriter, as WriteRecords<T>(IEnumerable<T>) writes them with the generated one: the header first when nothing has been written yet and CsvWriterOptions.HasHeader is set, then a record per element. For a record writer of your own, such as one for a type that has no generated writer, without registering it for the type (CsvRecordWriter.Register).

Type parameters

T: The type of the records.

Parameters

recordsIEnumerable<T>: The records, enumerated once.
recordWriterCsvRecordWriter<T>: Writes the header and the fields of each record.

Exceptions

ArgumentNullException: records or recordWriter is null.
ArgumentException: records contains null.
InvalidOperationException: A record is not valid (see EndRecord). That record is discarded; the records before it are written.
ObjectDisposedException: The writer has been disposed.

WriteRecordsAsync<T>(IAsyncEnumerable<T>, CancellationToken)

Added in v30.0.3

public ValueTask WriteRecordsAsync<T>(IAsyncEnumerable<T> records, CancellationToken cancellationToken = default)

Writes an asynchronous sequence of records as WriteRecords<T>(IEnumerable<T>) does, flushing asynchronously whenever the buffer is mostly full, so it never blocks on I/O.

Type parameters

T: The CsvRecordAttribute type.

Parameters

recordsIAsyncEnumerable<T>: The records, enumerated once.
cancellationTokenCancellationToken: Cancels the enumeration of records and writing to the destination.

Returns

A task that completes when every record is in the buffer and the full buffers have been written out.

Exceptions

ArgumentNullException: records is null.
ArgumentException: records contains null.
InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, or a record is not valid (see EndRecord). That record is discarded; the records before it are written.
FormatException: A member's format is not valid for its type.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

WriteRecordsAsync<T>(IEnumerable<T>, CancellationToken)

Added in v24.0.0

public ValueTask WriteRecordsAsync<T>(IEnumerable<T> records, CancellationToken cancellationToken = default)

Writes records as WriteRecords<T>(IEnumerable<T>) does, flushing asynchronously whenever the buffer is mostly full, so it never blocks on I/O.

Type parameters

T: The CsvRecordAttribute type.

Parameters

recordsIEnumerable<T>: The records, enumerated once.
cancellationTokenCancellationToken: Cancels writing to the destination.

Returns

A task that completes when every record is in the buffer and the full buffers have been written out.

Exceptions

ArgumentNullException: records is null.
ArgumentException: records contains null.
InvalidOperationException: T is not a CsvRecordAttribute type or its records cannot be written, or a record is not valid (see EndRecord). That record is discarded; the records before it are written.
FormatException: A member's format is not valid for its type.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

WriteRecordsAsync<T>(IAsyncEnumerable<T>, CsvRecordWriter<T>, CancellationToken)

Added in v34.0.0

public ValueTask WriteRecordsAsync<T>(IAsyncEnumerable<T> records, CsvRecordWriter<T> recordWriter, CancellationToken cancellationToken = default)

Writes an asynchronous sequence of records with recordWriter, as WriteRecords<T>(IEnumerable<T>, CsvRecordWriter<T>) does, flushing asynchronously whenever the buffer is mostly full, so it never blocks on I/O.

Type parameters

T: The type of the records.

Parameters

recordsIAsyncEnumerable<T>: The records, enumerated once.
recordWriterCsvRecordWriter<T>: Writes the header and the fields of each record.
cancellationTokenCancellationToken: Cancels the enumeration of records and writing to the destination.

Returns

A task that completes when every record is in the buffer and the full buffers have been written out.

Exceptions

ArgumentNullException: records or recordWriter is null.
ArgumentException: records contains null.
InvalidOperationException: A record is not valid (see EndRecord). That record is discarded; the records before it are written.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.

WriteRecordsAsync<T>(IEnumerable<T>, CsvRecordWriter<T>, CancellationToken)

Added in v34.0.0

public ValueTask WriteRecordsAsync<T>(IEnumerable<T> records, CsvRecordWriter<T> recordWriter, CancellationToken cancellationToken = default)

Writes records with recordWriter, as WriteRecords<T>(IEnumerable<T>, CsvRecordWriter<T>) does, flushing asynchronously whenever the buffer is mostly full, so it never blocks on I/O.

Type parameters

T: The type of the records.

Parameters

recordsIEnumerable<T>: The records, enumerated once.
recordWriterCsvRecordWriter<T>: Writes the header and the fields of each record.
cancellationTokenCancellationToken: Cancels writing to the destination.

Returns

A task that completes when every record is in the buffer and the full buffers have been written out.

Exceptions

ArgumentNullException: records or recordWriter is null.
ArgumentException: records contains null.
InvalidOperationException: A record is not valid (see EndRecord). That record is discarded; the records before it are written.
ObjectDisposedException: The writer has been disposed.
OperationCanceledException: cancellationToken was canceled.