Class in CsvHelper
A forward-only CSV reader. Input is parsed as UTF-8 bytes with SIMD instructions; fields are exposed as spans into the read buffer and are only materialized as strings or numbers when asked for.
public sealed class CsvReader : IDisposable, IAsyncDisposableCsvHelperCsvHelper.dllSpans returned for a record are valid until the next call to Read or ReadAsync.
A reader is not thread-safe: use it from one thread at a time, and finish each async call before starting the next. Nothing checks this; two threads reading one reader get wrong records, not an exception. To map records on several threads, use ParallelEnumerate<T>(Func<CsvReader, T>, int). The options, the record mappers and the CsvDynamicRecords a reader returns do not change, so they can be shared between threads.
public long ByteOffset { get; }The offset, in bytes of UTF-8 input, where the current record starts, counted from the start of the input (a byte order mark included), for progress reports and error messages. UTF-16 input (strings, text readers and streams with another encoding) is counted in the bytes of its UTF-8 form.
public CsvRow Current { get; }The current record as a CsvRow. Valid until the next read.
public int FieldCount { get; }The number of fields in the current record.
public IReadOnlyList<string> Headers { get; }The header names. Empty when CsvReaderOptions.HasHeader is false. Accessing this before the first Read reads the header synchronously; async callers can use ReadHeaderAsync first.
public long LineNumber { get; }The 1-based line of the input where the current record starts, counting every line: those inside quoted fields, empty lines, comments and the header too. Requires CsvReaderOptions.TrackLineNumbers.
public CsvReaderOptions Options { get; }The options this reader was created with.
public ReadOnlySpan<byte> RawRecord { get; }The raw bytes of the current record as they appear in the input (UTF-8), without the line break. Empty before the first record and at the end of the input. Valid until the next read.
public long RowNumber { get; }The 1-based number of the current data record (the header is not counted).
public char Separator { get; }The separator in use. When it is detected from the input, getting it before the first Read reads the header (or the start of the input) synchronously. '\0' in CsvMode.FixedWidth mode, which has no separator.
public CsvField this[int index] { get; }Gets field index of the current record. The field is valid until the next read.
indexintindex is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public CsvField this[string name] { get; }Gets the field with the given header name. The field is valid until the next read.
namestringname is null.public static CsvReader Create(ReadOnlyMemory<byte> utf8, CsvReaderOptions? options = null)Creates a reader over UTF-8 bytes in memory. Array backed memory is read in place without copying.
utf8ReadOnlyMemory<byte>optionsCsvReaderOptions?null for CsvReaderOptions.Default.options sets a character that is not ASCII, or uses the same character for two purposes.public static CsvReader Create(byte[] utf8, CsvReaderOptions? options = null)Creates a reader over UTF-8 bytes in memory. The array is read in place without copying.
utf8byte[]optionsCsvReaderOptions?null for CsvReaderOptions.Default.utf8 is null.options sets a character that is not ASCII, or uses the same character for two purposes.public static CsvReader Create(Stream stream, CsvReaderOptions? options = null, bool leaveOpen = false)Creates a reader over a stream. The stream is read sequentially; it does not need to be seekable.
streamStreamoptionsCsvReaderOptions?null for CsvReaderOptions.Default. For a CsvSeparatorStream, the separator is its CsvSeparatorStream.Replacement, and the stream takes the quoting, escape and comment rules of these options.leaveOpenboolstream stays open when the reader is disposed.stream until it is needed.stream is null.options sets a character that is not ASCII, or uses the same character for two purposes; or, for a CsvSeparatorStream, sets another separator or FixedWidth mode, or a character its separator contains.stream is a CsvSeparatorStream and CsvReaderOptions.Encoding is neither UTF-8 nor a single-byte encoding.stream is a CsvSeparatorStream that has already been read from.public static CsvReader Create(TextReader textReader, CsvReaderOptions? options = null, bool leaveOpen = false)Creates a reader over UTF-16 text from a TextReader.
textReaderTextReaderoptionsCsvReaderOptions?null for CsvReaderOptions.Default.leaveOpenbooltextReader stays open when the reader is disposed.textReader until it is needed.textReader is null.options sets a character that is not ASCII, or uses the same character for two purposes.public void Dispose()Returns the buffers to their pools and disposes the stream or text reader being read, unless the reader was created with leaveOpen. Calling it again does nothing.
public ValueTask DisposeAsync()Returns the buffers to their pools and asynchronously disposes the stream or text reader being read, unless the reader was created with leaveOpen. Calling it again does nothing.
public IEnumerable<T> EnumerateRecords<T>(T record) where T : classReads the remaining records into record, one instance of a CsvRecordAttribute class that is refilled for every record, so that reading allocates no object per record (strings are still created, unless CsvReaderOptions.PoolStrings shares them). Each step of the enumeration returns the same instance: copy what you keep. The header is read and the columns are resolved by this call.
TrecordTrecord each time it moves, and can be enumerated once.record is null.T is not a CsvRecordAttribute type, or this reader is the one a ParallelEnumerate<T>(Func<CsvReader, T>, int) selector got.T has members that only its constructor or an object initializer can set (constructor parameters, init accessors); thrown by the enumeration.T requires.Every member that a record sets is set again: a member whose column is optional and missing from the header keeps the value it has. Members whose type is itself a record type get a new instance for each record.
public IAsyncEnumerable<T> EnumerateRecordsAsync<T>(T record, CancellationToken cancellationToken = default) where T : classAsynchronously reads the remaining records into record, one instance that is refilled for every record. See EnumerateRecords; as in GetRecordsAsync, every exception is thrown by the enumeration.
TrecordTcancellationTokenCancellationTokenWithCancellation is combined with this one.record each time it moves, and can be enumerated once.public static CsvReader FromFile(string path, CsvReaderOptions? options = null, FileOptions fileOptions = FileOptions.SequentialScan)Opens a file for reading, sharing it with other readers. The reader closes the file when it is disposed. See Create(Stream, CsvReaderOptions, bool).
pathstringoptionsCsvReaderOptions?null for CsvReaderOptions.Default.fileOptionsFileOptionspath is empty, or options sets a character that is not ASCII, or uses the same character for two purposes.path is null.public static CsvReader FromText(string text, CsvReaderOptions? options = null)Creates a reader over CSV text held in a string.
textstringoptionsCsvReaderOptions?null for CsvReaderOptions.Default.text is null.options sets a character that is not ASCII, or uses the same character for two purposes.public CsvReader.AsyncEnumerator GetAsyncEnumerator(CancellationToken cancellationToken = default)Returns an async enumerator so records can be read with await foreach.
cancellationTokenCancellationTokenpublic int GetChars(int index, Span<char> destination)Copies field index into destination as UTF-16.
indexintdestinationSpan<char>destination.destination is too small for the value.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public CsvReader.Enumerator GetEnumerator()Returns an enumerator so records can be read with foreach.
public int GetFieldIndex(string name)Gets the index of the column with the given header name. See TryGetFieldIndex(string, out int).
namestringname is null.public int GetFieldIndex(string name, int nameIndex)Gets the index of the column at nameIndex among those with the name. See TryGetFieldIndex(string, int, out int).
namestringnameIndexintname is null.nameIndex is negative.public ReadOnlySpan<byte> GetRawSpan(int index)Gets the raw bytes of field index exactly as they appear in the input.
indexintindex is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public T GetRecord<T>()Reads the current record as a T, a CsvRecordAttribute type. The mapper is created on the first call (reading the header if needed) and reused while T stays the same.
TT with the values of the current record.T is not a CsvRecordAttribute type.T requires.public T GetRecord<T>(CsvRecordMapper<T> mapper)Reads the current record with mapper, such as a projection that reads only some members (CsvRecordMapper.CreateProjection) or a hand-written mapper. A failure is reported as by GetRecord<T>().
TmapperCsvRecordMapper<T>mapper read.mapper is null.public void GetRecord<T>(T record) where T : classReads the current record into record, an existing instance of a CsvRecordAttribute class, instead of creating one. See EnumerateRecords.
TrecordTrecord is null.T is not a CsvRecordAttribute type.T has members that only its constructor or an object initializer can set.T requires.public IEnumerable<T> GetRecords<T>()Reads the remaining records as T, a CsvRecordAttribute type. The header is read and the columns are resolved by this call; the records are read as they are enumerated, and the exceptions of Read are thrown by the enumeration. A record that cannot be read as T throws a CsvFormatException that names the record, the field and the member, with the exception of the field or member as its Exception.InnerException, unless CsvReaderOptions.OnRecordError skips it.
TT is not a CsvRecordAttribute type, or this reader is the one a ParallelEnumerate<T>(Func<CsvReader, T>, int) selector got.T requires.public IAsyncEnumerable<T> GetRecordsAsync<T>(CancellationToken cancellationToken = default)Asynchronously reads the remaining records as T, a CsvRecordAttribute type. The header is read and the columns are resolved when the enumeration starts, so every exception, including those of GetRecords, is thrown by the enumeration.
TcancellationTokenCancellationTokenWithCancellation is combined with this one.public ReadOnlySpan<byte> GetSpan(int index)Gets the value of field index of the current record as UTF-8 bytes, decoded as the CsvReaderOptions.Mode says: with quotes removed and escaped quotes unescaped, with escape characters removed, or as the text of its column. The span is valid until the next read.
indexintindex is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.A field past the end of the record reads as empty, unless CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw. The other field accessors behave the same way.
public ReadOnlySpan<byte> GetSpan(string name)Gets the value of the field with the given header name. See GetSpan(int).
namestringname is null.public string GetString(int index)Gets field index as a string. With CsvReaderOptions.PoolStrings, a value seen before in the same column may return the same string instance.
indexintindex is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public string GetString(string name)Gets the field with the given header name as a string. See GetString(int).
namestringname is null.public string? GetStringOrNull(int index)Gets field index as a string, or null when it is one of CsvReaderOptions.NullValues. An empty field is "" unless "" is one of them.
indexintnull.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public string? GetStringOrNull(string name)Gets the field with the given header name as a string, or null. See GetStringOrNull(int).
namestringnull.name is null.public bool IsEmpty(int index)Whether field index is empty (or missing).
indexinttrue when the value is empty ("" included) or the record has no such field; otherwise false.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public bool IsNull(int index)Whether field index is null: empty (or missing), or one of CsvReaderOptions.NullValues.
indexinttrue when the value is empty, the record has no such field or the value is one of CsvReaderOptions.NullValues; otherwise false.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public IEnumerable<T> ParallelEnumerate<T>(int maxDegreeOfParallelism = -1)Reads the remaining records as T, a CsvRecordAttribute type, on several threads and returns them in input order. The header is read and the columns are resolved by this call. See ParallelEnumerate<T>(Func<CsvReader, T>, int).
TmaxDegreeOfParallelismintmaxDegreeOfParallelism is 0 or less than -1.T is not a CsvRecordAttribute type, or this reader is the one a ParallelEnumerate<T>(Func<CsvReader, T>, int) selector got.T requires.public IEnumerable<T> ParallelEnumerate<T>(Func<CsvReader, T> selector, int maxDegreeOfParallelism = -1)Maps the remaining records with selector on several threads and returns the results in input order.
TmaxDegreeOfParallelismintselector is null.maxDegreeOfParallelism is 0 or less than -1.The selector gets a reader positioned on one record. Use its field accessors (GetString(int), GetSpan(int), Parse<T>(int, Func<string, IFormatProvider, T>) and so on) and return a value; the reader and its spans are only valid during the call, and Read cannot be called on it. Calls run concurrently on different threads, each thread with its own reader. The input is read and checked by one thread at a time, in order, so CsvReaderOptions.OnMalformedRecord is never called concurrently. Exceptions from the reader or the selector are thrown by the enumerator after the results of the preceding records. This reader must not be used otherwise until the enumeration ends.
net10.0
public T Parse<T>(int index) where T : ISpanParsable<T>Parses field index as T with the configured format provider.
TindexintT.T.T is not one of the built-in types.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.The built-in types are parsed from the UTF-8 bytes of the field:
Z in the field gives a DateTimeKind.Local or DateTimeKind.Utc value as DateTimeStyles.RoundtripKind describes. ParseExact<T>(int, string) parses an exact format.Read, Write) as Enum.TryParse reads them, ignoring case. Enums are not ISpanParsable<T>, so on .NET 8 and later Parse<MyEnum> calls the overload of CsvEnumExtensions, an extension method.On .NET 8 and later, any other type (DateOnly, TimeSpan, BigInteger, your own types) is parsed with its own ISpanParsable<T> parser, from the field decoded to chars. On .NET Framework and .NET Standard, TimeSpan, BigInteger (in NumberStyles.Integer style), char and IPAddress are parsed from the field decoded to a string, as .NET parses them, and other types are not supported: parse them with Parse<T>(int, Func<string, IFormatProvider, T>).
netstandard2.1, netstandard2.0, net47
public T Parse<T>(int index)Parses field index as T with the configured format provider.
TindexintT.T.T is not one of the built-in types.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.The built-in types are parsed from the UTF-8 bytes of the field:
Z in the field gives a DateTimeKind.Local or DateTimeKind.Utc value as DateTimeStyles.RoundtripKind describes. ParseExact<T>(int, string) parses an exact format.Read, Write) as Enum.TryParse reads them, ignoring case. Enums are not ISpanParsable<T>, so on .NET 8 and later Parse<MyEnum> calls the overload of CsvEnumExtensions, an extension method.On .NET 8 and later, any other type (DateOnly, TimeSpan, BigInteger, your own types) is parsed with its own ISpanParsable<T> parser, from the field decoded to chars. On .NET Framework and .NET Standard, TimeSpan, BigInteger (in NumberStyles.Integer style), char and IPAddress are parsed from the field decoded to a string, as .NET parses them, and other types are not supported: parse them with Parse<T>(int, Func<string, IFormatProvider, T>).
net10.0
public T Parse<T>(string name) where T : ISpanParsable<T>Parses the field with the given header name as T. See Parse<T>(int).
Tnamestringname is null.T.T.T is not one of the built-in types.netstandard2.1, netstandard2.0, net47
public T Parse<T>(string name)Parses the field with the given header name as T. See Parse<T>(int).
Tnamestringname is null.T.T.T is not one of the built-in types.public T Parse<T>(int index, Func<string, IFormatProvider, T> parser)Parses field index with parser, which gets the field as a string and the configured format provider, for example reader.Parse(3, TimeSpan.Parse).
Tparser returns.indexintparserFunc<string, IFormatProvider, T>parser returns.parser is null.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.net10.0
public T Parse<T>(int index, IFormatProvider provider) where T : ISpanParsable<T>Parses field index as T with provider instead of the configured format provider. See Parse<T>(int).
TindexintproviderIFormatProviderprovider is null.T.T.T is not one of the built-in types.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.netstandard2.1, netstandard2.0, net47
public T Parse<T>(int index, IFormatProvider provider)Parses field index as T with provider instead of the configured format provider. See Parse<T>(int).
TindexintproviderIFormatProviderprovider is null.T.T.T is not one of the built-in types.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public T Parse<T>(string name, Func<string, IFormatProvider, T> parser)Parses the field with the given header name with parser. See Parse<T>(int, Func<string, IFormatProvider, T>).
Tparser returns.namestringparserFunc<string, IFormatProvider, T>parser returns.name or parser is null.public T ParseExact<T>(int index, string format)Parses field index as a DateTime or DateTimeOffset in exactly the given format, such as "yyyyMMdd", with the configured format provider. A time zone offset or Z in the field gives a DateTimeKind.Local or DateTimeKind.UtcDateTime as DateTimeStyles.RoundtripKind describes; a DateTimeOffset field without an offset gets the local time zone's.
Tindexintformatstringformat is null.T is neither DateTime nor DateTimeOffset.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public T ParseExact<T>(int index, string[] formats)Parses field index as a DateTime or DateTimeOffset in exactly one of the given formats, tried in order, such as "yyyy-MM-dd" and "dd/MM/yyyy" for a file that mixes them, with the configured format provider. See ParseExact<T>(int, string).
Tindexintformatsstring[]formats is null.T is neither DateTime nor DateTimeOffset.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public T ParseExact<T>(int index, string format, IFormatProvider provider)Parses field index as a DateTime or DateTimeOffset in exactly the given format with provider. See ParseExact<T>(int, string).
TindexintformatstringproviderIFormatProviderformat or provider is null.T is neither DateTime nor DateTimeOffset.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public T ParseExact<T>(int index, string[] formats, IFormatProvider provider)Parses field index as a DateTime or DateTimeOffset in exactly one of the given formats, tried in order, with provider. See ParseExact<T>(int, string[]).
Tindexintformatsstring[]providerIFormatProviderformats or provider is null.T is neither DateTime nor DateTimeOffset.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public bool Read()Advances to the next record, reading the header first if it has not been read. Empty lines, comments and the records that the options say to skip are passed over.
true when the reader is positioned on a record; false at the end of the input.public ValueTask<bool> ReadAsync(CancellationToken cancellationToken = default)Asynchronously advances to the next record, reading the header first if it has not been read. Completes synchronously while records that have already been read from the source remain. See Read.
cancellationTokenCancellationTokentrue when the reader is positioned on a record; false at the end of the input.cancellationToken was canceled.public void ReadHeader()Reads the header row (if any) without advancing to the first data record. Without a header, it still reads the start of the input, so that Separator is known. Once the header has been read, calling it while the reader is on a record makes that record the new header, for files with several data sets one after the other: Headers, the by-name lookups and the record mappers created afterwards use it, and the record does not count as a data record. Otherwise it does nothing.
public ValueTask ReadHeaderAsync(CancellationToken cancellationToken = default)Asynchronously reads the header row (if any) without advancing to the first data record, or makes the current record the new header. See ReadHeader.
cancellationTokenCancellationTokencancellationToken was canceled.public bool TryGetFieldIndex(string name, out int index)Finds the index of the column with the given header name. An exact match wins; otherwise the name is matched ignoring case and surrounding whitespace. Both names are changed by CsvReaderOptions.NormalizeHeaderName first, if it is set. Reads the header first if it has not been read (see ReadHeader).
namestringindexintname is null.When several columns have the same name, the first one wins; TryGetFieldIndex(string, int, out int) finds the others. Without a header (CsvReaderOptions.HasHeader is false), no name is found.
public bool TryGetFieldIndex(string name, int nameIndex, out int index)Finds the index of a column whose name several columns have: the one at nameIndex among them, in header order. Names are matched as by TryGetFieldIndex(string, out int): among the exact matches when there are enough, else among those that match ignoring case and surrounding whitespace.
namestringnameIndexintindexintname is null.nameIndex is negative.public bool TryGetRecord<T>(CsvRecordMapper<T> mapper, out T record)Reads the current record with mapper, as GetRecord<T>(CsvRecordMapper<T>) does, unless it cannot be read and CsvReaderOptions.OnRecordError skips it, as GetRecords skips such records.
TmapperCsvRecordMapper<T>recordTT when it was skipped.true when the record was read; false when the handler skipped it.mapper is null.net10.0
public bool TryParse<T>(int index, out T value) where T : ISpanParsable<T>Tries to parse field index as T. See Parse<T>(int).
TindexintvalueTT when parsing fails.T is not one of the built-in types.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.netstandard2.1, netstandard2.0, net47
public bool TryParse<T>(int index, out T value)Tries to parse field index as T. See Parse<T>(int).
TindexintvalueTT when parsing fails.T is not one of the built-in types.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public bool TryParse<T>(int index, CsvTryParser<T> parser, out T value)Tries to parse field index with parser, which gets the field as a string and the configured format provider.
Tparser parses.indexintparserCsvTryParser<T>valueTparser produced.parser: whether the field could be parsed.parser is null.index is negative.index is not less than FieldCount and CsvReaderOptions.MissingField is CsvMissingFieldHandling.Throw.public bool TryValidateHeader<T>(out IReadOnlyList<string> missingColumns)Checks, without reading a record and without throwing, that the header has every column that T requires; see ValidateHeader.
TmissingColumnsIReadOnlyList<string>Order.Price ('Unit Price'). Empty when none is missing.T is not a CsvRecordAttribute type.public void ValidateHeader<T>()Checks, without reading a record, that the header has every column that T requires: the check that GetRecords makes. The header is read if it has not been.
TT requires, which the message names, or the input has no header and required members have no column index.T is not a CsvRecordAttribute type.