public static class CsvQueryable
Namespace
CsvHelper.Linq
Assembly
CsvHelper.Linq.dll
Builds
net10.0 netstandard2.1 netstandard2.0 net47

Remarks

A query reads its source each time it runs, and pushes what it can into the reader: it reads only the members of the records that the query uses (with record types whose assembly references CsvHelper.Linq, which makes the source generator write the projections it needs), skips rows without parsing them, and filters records before it reads the members that only the rest of the query uses. Any LINQ operator can be used; LINQ to Objects runs those that the reader does not. Queries of other LINQ providers in a CSV query, such as tables of Entity Framework Core, run on their provider, and joins with them ask only for the rows with the keys of the CSV records.

The query provider compiles lambdas and uses reflection, so it is not supported with native AOT or trimming.

Methods

AsCsvAsync<T>(IQueryable<T>)

Added in v34.0.0static
public static CsvAsyncQuery<T> AsCsvAsync<T>(this IQueryable<T> source)

Runs a CSV query asynchronously: await foreach over the result, or call its asynchronous operators, such as CsvAsyncQuery<T>.ToListAsync and CsvAsyncQuery<T>.CountAsync(CancellationToken).

Type parameters

T
The type of the elements.

Parameters

sourceIQueryable<T>
A query over a CSV source, such as one that LINQ operators returned.

Returns

CsvAsyncQuery<T>
The asynchronous view of the query.

Exceptions

ArgumentNullException
source is null.
ArgumentException
source is not a CSV query.

View source

FromFile<T>(string, CsvQueryOptions)

Added in v34.0.0static
public static CsvTable<T> FromFile<T>(string path, CsvQueryOptions? options = null)

Queries and changes the records of a CSV file, which is opened each time a query runs.

Type parameters

T
The CsvRecordAttribute type of the records.

Parameters

pathstring
The path of the file.
optionsCsvQueryOptions?
How the file is read and written, or null for the defaults.

Returns

CsvTable<T>
The table of the file's records.

Exceptions

View source

public static CsvQuery<CsvDynamicRecord> FromStream(Func<Stream> open, CsvQueryOptions? options = null)

Queries the rows of CSV streams as dynamic records: open opens one each time a query runs.

Parameters

openFunc<Stream>
Opens the stream, positioned at the start of the CSV.
optionsCsvQueryOptions?
How the streams are read, or null for the defaults.

Returns

CsvQuery<CsvDynamicRecord>
The query of all the rows.

Exceptions

View source

public static CsvQuery<T> FromStream<T>(Func<Stream> open, CsvQueryOptions? options = null)

Queries the records of CSV streams: open opens one each time a query runs, which is disposed after it.

Type parameters

T
The CsvRecordAttribute type of the records.

Parameters

openFunc<Stream>
Opens the stream, positioned at the start of the CSV.
optionsCsvQueryOptions?
How the streams are read, or null for the defaults.

Returns

CsvQuery<T>
The query of all the records.

Exceptions

View source

public static CsvQuery<CsvDynamicRecord> FromTextReader(Func<TextReader> open, CsvQueryOptions? options = null)

Queries the rows of CSV text readers as dynamic records: open opens one each time a query runs.

Parameters

openFunc<TextReader>
Opens the text reader, positioned at the start of the CSV.
optionsCsvQueryOptions?
How the text is read, or null for the defaults.

Returns

CsvQuery<CsvDynamicRecord>
The query of all the rows.

Exceptions

View source

public static CsvQuery<T> FromTextReader<T>(Func<TextReader> open, CsvQueryOptions? options = null)

Queries the records of CSV text readers: open opens one each time a query runs, which is disposed after it.

Type parameters

T
The CsvRecordAttribute type of the records.

Parameters

openFunc<TextReader>
Opens the text reader, positioned at the start of the CSV.
optionsCsvQueryOptions?
How the text is read, or null for the defaults.

Returns

CsvQuery<T>
The query of all the records.

Exceptions

View source

Query(CsvReader, CsvQueryOptions)

Added in v34.0.0static
public static CsvQuery<CsvDynamicRecord> Query(this CsvReader reader, CsvQueryOptions? options = null)

Queries the remaining rows of a reader as dynamic records, from where it is. The query can run once; one that uses it in more than one place reads its rows once, into memory.

Parameters

readerCsvReader
The reader.
optionsCsvQueryOptions?
How much the query pushes into the reader, or null for the defaults.

Returns

CsvQuery<CsvDynamicRecord>
The query of the remaining rows.

Exceptions

ArgumentNullException
reader is null.

View source

Query<T>(CsvReader, CsvQueryOptions)

Added in v34.0.0static
public static CsvQuery<T> Query<T>(this CsvReader reader, CsvQueryOptions? options = null)

Queries the remaining records of a reader, from where it is. The query can run once, and leaves the reader open; its options are the reader's (CsvQueryOptions.ReaderOptions is not used). A query that uses it in more than one place, such as both sides of a self-join, reads its records once, into memory.

Type parameters

T
The CsvRecordAttribute type of the records.

Parameters

readerCsvReader
The reader.
optionsCsvQueryOptions?
How much the query pushes into the reader, or null for the defaults.

Returns

CsvQuery<T>
The query of the remaining records.

Exceptions

ArgumentNullException
reader is null.

View source

public static long Update(this CsvTable<CsvDynamicRecord> table, Expression<Func<CsvDynamicRecord, bool>> predicate, Action<IDictionary<string, string?>> update)

Changes the dynamic rows of a file that match a condition: update changes the values of each, by column name, and only the fields whose values changed are written again; the rest of the file is kept byte for byte. The file is rewritten next to itself and replaced when the new one is complete, so a failure leaves it as it was.

Parameters

tableCsvTable<CsvDynamicRecord>
The table of the file.
predicateExpression<Func<CsvDynamicRecord, bool>>
The condition of the rows to change.
updateAction<IDictionary<string, string?>>
Changes the values of a row, such as row => row["Status"] = "Open".

Returns

long
The number of rows changed.

Exceptions

ArgumentNullException
An argument is null.
InvalidOperationException
The update sets a column that the file does not have.
NotSupportedException
The file is not UTF-8, is fixed-width, or quotes with another character than ".

View source

public static ValueTask<long> UpdateAsync(this CsvTable<CsvDynamicRecord> table, Expression<Func<CsvDynamicRecord, bool>> predicate, Action<IDictionary<string, string?>> update, CancellationToken cancellationToken = default)

Changes the dynamic rows of a file that match a condition, asynchronously; see Update.

Parameters

tableCsvTable<CsvDynamicRecord>
The table of the file.
predicateExpression<Func<CsvDynamicRecord, bool>>
The condition of the rows to change.
updateAction<IDictionary<string, string?>>
Changes the values of a row.
cancellationTokenCancellationToken
Cancels the rewrite, which leaves the file as it was.

Returns

ValueTask<long>
The number of rows changed.

Exceptions

ArgumentNullException
An argument is null.
InvalidOperationException
The update sets a column that the file does not have.
NotSupportedException
The file is not UTF-8, is fixed-width, or quotes with another character than ".

View source