Class CsvHelper

Namespace

WeihanLi.Npoi

Assembly

WeihanLi.Npoi.dll

CsvHelper provides utilities for reading and writing CSV files, supporting conversion between CSV data and DataTables or strongly-typed entities.

public static class CsvHelper

Inheritance

object

CsvHelper

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

CsvQuoteCharacter

CSV quote character used to escape values containing special characters, " by default. Values containing the separator character will be wrapped with this quote character.

public static char CsvQuoteCharacter

Field Value

char

CsvSeparatorCharacter

CSV separator character, ',' by default. Can be changed to support different CSV formats (e.g., ';' for European format).

public static char CsvSeparatorCharacter

Field Value

char

Methods

GetCsvLines<TEntity>(IEnumerable<TEntity>, CsvOptions?)

Converts a collection of entities to a sequence of CSV formatted lines. For basic types, each entity is converted to a single line. For complex types, properties are mapped to columns with proper CSV escaping. Values containing separator characters are automatically quoted.

public static IEnumerable<string> GetCsvLines<TEntity>(this IEnumerable<TEntity> entities, CsvOptions? csvOptions = null)

Parameters

entities IEnumerable<TEntity>

The collection of entities to convert

csvOptions CsvOptions

Optional custom CSV formatting options

Returns

IEnumerable<string>

CSV formatted lines

Type Parameters

TEntity

The entity type to convert

GetCsvText(DataTable?, bool)

Converts a DataTable to CSV formatted text with optional header (default includes header).

public static string GetCsvText(this DataTable? dataTable, bool includeHeader = true)

Parameters

dataTable DataTable

The DataTable to convert

includeHeader bool

Whether to include column names as headers

Returns

string

CSV data as a string

GetCsvText(DataTable?, CsvOptions)

Converts a DataTable to CSV formatted text with custom options. Column names are decoded if they were previously encoded to handle duplicates. Values containing separator characters are automatically quoted.

public static string GetCsvText(this DataTable? dataTable, CsvOptions csvOptions)

Parameters

dataTable DataTable

The DataTable to convert

csvOptions CsvOptions

Custom CSV formatting options

Returns

string

CSV data as a string, or empty string if the DataTable is null or empty

GetCsvText<TEntity>(IEnumerable<TEntity>, bool)

Converts a collection of entities to CSV formatted text with optional header (default includes header).

public static string GetCsvText<TEntity>(this IEnumerable<TEntity> entities, bool includeHeader = true)

Parameters

entities IEnumerable<TEntity>

The collection of entities to convert

includeHeader bool

Whether to include property names as column headers

Returns

string

CSV data as a string

Type Parameters

TEntity

The entity type to convert

GetCsvText<TEntity>(IEnumerable<TEntity>, CsvOptions)

Converts a collection of entities to CSV formatted text with custom options.

public static string GetCsvText<TEntity>(this IEnumerable<TEntity> entities, CsvOptions csvOptions)

Parameters

entities IEnumerable<TEntity>

The collection of entities to convert

csvOptions CsvOptions

Custom CSV formatting options

Returns

string

CSV data as a string

Type Parameters

TEntity

The entity type to convert

GetEntities<TEntity>(IEnumerable<string>, CsvOptions?)

Converts CSV lines to a lazy-loaded sequence of strongly-typed entities. Supports both basic types and complex objects with property mapping. For complex types, column headers are matched to property names or configured column titles.

public static IEnumerable<TEntity?> GetEntities<TEntity>(IEnumerable<string> csvLines, CsvOptions? csvOptions = null)

Parameters

csvLines IEnumerable<string>

Enumerable collection of CSV lines

csvOptions CsvOptions

Optional custom CSV parsing options

Returns

IEnumerable<TEntity>

A lazy-loaded enumerable of entities

Type Parameters

TEntity

The entity type to map CSV data to

GetEntities<TEntity>(string, CsvOptions?)

Parses CSV text and converts it to a lazy-loaded sequence of strongly-typed entities.

public static IEnumerable<TEntity?> GetEntities<TEntity>(string csvText, CsvOptions? csvOptions = null)

Parameters

csvText string

CSV data as a string

csvOptions CsvOptions

Optional custom CSV parsing options

Returns

IEnumerable<TEntity>

A lazy-loaded enumerable of entities

Type Parameters

TEntity

The entity type to map CSV data to

GetEntityList<TEntity>(IEnumerable<string>, CsvOptions?)

Converts CSV lines to a strongly-typed entity list.

public static List<TEntity?> GetEntityList<TEntity>(IEnumerable<string> csvLines, CsvOptions? csvOptions = null)

Parameters

csvLines IEnumerable<string>

Enumerable collection of CSV lines

csvOptions CsvOptions

Optional custom CSV parsing options

Returns

List<TEntity>

A list of entities populated from CSV data

Type Parameters

TEntity

The entity type to map CSV data to

GetEntityList<TEntity>(string, CsvOptions?)

Parses CSV text and converts it to a strongly-typed entity list.

public static List<TEntity?> GetEntityList<TEntity>(string csvText, CsvOptions? csvOptions = null)

Parameters

csvText string

CSV data as a string

csvOptions CsvOptions

Optional custom CSV parsing options

Returns

List<TEntity>

A list of entities populated from CSV data

Type Parameters

TEntity

The entity type to map CSV data to

ParseLine(string)

Parses a single CSV line into individual field values using default options.

public static IReadOnlyList<string> ParseLine(string line)

Parameters

line string

The CSV line to parse

Returns

IReadOnlyList<string>

A read-only list of field values

ParseLine(string, CsvOptions)

Parses a single CSV line into individual field values with custom options. Handles quoted values, escaped quotes, and separator characters within quoted fields.

public static IReadOnlyList<string> ParseLine(string line, CsvOptions csvOptions)

Parameters

line string

The CSV line to parse

csvOptions CsvOptions

Custom CSV parsing options (separator, quote character)

Returns

IReadOnlyList<string>

A read-only list of field values

Exceptions

ArgumentException

Thrown when the line contains improperly escaped quotes

ToCsvBytes(DataTable)

Converts a DataTable to CSV formatted byte array with default encoding (includes header).

public static byte[] ToCsvBytes(this DataTable dt)

Parameters

dt DataTable

The DataTable to convert

Returns

byte[]

CSV data as a byte array

ToCsvBytes(DataTable, bool)

Converts a DataTable to CSV formatted byte array with optional header.

public static byte[] ToCsvBytes(this DataTable dataTable, bool includeHeader)

Parameters

dataTable DataTable

The DataTable to convert

includeHeader bool

Whether to include column headers in the output

Returns

byte[]

CSV data as a byte array

ToCsvBytes(DataTable, CsvOptions)

Converts a DataTable to CSV formatted byte array with custom options.

public static byte[] ToCsvBytes(this DataTable dataTable, CsvOptions csvOptions)

Parameters

dataTable DataTable

The DataTable to convert

csvOptions CsvOptions

Custom CSV formatting options

Returns

byte[]

CSV data as a byte array

ToCsvBytes<TEntity>(IEnumerable<TEntity>)

Converts a collection of entities to CSV formatted byte array with default encoding (includes header).

public static byte[] ToCsvBytes<TEntity>(this IEnumerable<TEntity> entities)

Parameters

entities IEnumerable<TEntity>

The collection of entities to convert

Returns

byte[]

CSV data as a byte array

Type Parameters

TEntity

The entity type to convert

ToCsvBytes<TEntity>(IEnumerable<TEntity>, bool)

Converts a collection of entities to CSV formatted byte array with optional header.

public static byte[] ToCsvBytes<TEntity>(this IEnumerable<TEntity> entities, bool includeHeader)

Parameters

entities IEnumerable<TEntity>

The collection of entities to convert

includeHeader bool

Whether to include property names as column headers

Returns

byte[]

CSV data as a byte array

Type Parameters

TEntity

The entity type to convert

ToCsvBytes<TEntity>(IEnumerable<TEntity>, CsvOptions)

Converts a collection of entities to CSV formatted byte array with custom options.

public static byte[] ToCsvBytes<TEntity>(this IEnumerable<TEntity> entities, CsvOptions csvOptions)

Parameters

entities IEnumerable<TEntity>

The collection of entities to convert

csvOptions CsvOptions

Custom CSV formatting options

Returns

byte[]

CSV data as a byte array

Type Parameters

TEntity

The entity type to convert

ToCsvFile(DataTable, string)

Saves a DataTable to a CSV file with default options (includes header).

public static bool ToCsvFile(this DataTable dt, string filePath)

Parameters

dt DataTable

The DataTable to export

filePath string

The destination file path

Returns

bool

True if the file was successfully created; otherwise, false

ToCsvFile(DataTable, string, bool)

Saves a DataTable to a CSV file with optional header.

public static bool ToCsvFile(this DataTable dataTable, string filePath, bool includeHeader)

Parameters

dataTable DataTable

The DataTable to export

filePath string

The destination file path

includeHeader bool

Whether to include column headers in the output

Returns

bool

True if the file was successfully created; otherwise, false

ToCsvFile(DataTable, string, CsvOptions)

Saves a DataTable to a CSV file with custom CSV options.

public static bool ToCsvFile(this DataTable dataTable, string filePath, CsvOptions csvOptions)

Parameters

dataTable DataTable

The DataTable to export

filePath string

The destination file path

csvOptions CsvOptions

Custom CSV formatting options (encoding, separator, quote character, etc.)

Returns

bool

True if the file was successfully created; otherwise, false

ToCsvFileAsync<TEntity>(IEnumerable<TEntity>, string, CsvOptions?)

Asynchronously saves a collection of entities to a CSV file. This method is more memory-efficient for large collections as it streams lines to the file.

public static Task<bool> ToCsvFileAsync<TEntity>(this IEnumerable<TEntity> entities, string filePath, CsvOptions? csvOptions = null)

Parameters

entities IEnumerable<TEntity>

The collection of entities to export

filePath string

The destination file path

csvOptions CsvOptions

Optional custom CSV formatting options

Returns

Task<bool>

A task that represents the asynchronous operation, containing true if successful

Type Parameters

TEntity

The entity type to export

ToCsvFile<TEntity>(IEnumerable<TEntity>, string)

Saves a collection of entities to a CSV file with default options (includes header).

public static bool ToCsvFile<TEntity>(this IEnumerable<TEntity> entities, string filePath)

Parameters

entities IEnumerable<TEntity>

The collection of entities to export

filePath string

The destination file path

Returns

bool

True if the file was successfully created; otherwise, false

Type Parameters

TEntity

The entity type to export

ToCsvFile<TEntity>(IEnumerable<TEntity>, string, bool)

Saves a collection of entities to a CSV file with optional header.

public static bool ToCsvFile<TEntity>(this IEnumerable<TEntity> entities, string filePath, bool includeHeader)

Parameters

entities IEnumerable<TEntity>

The collection of entities to export

filePath string

The destination file path

includeHeader bool

Whether to include property names as column headers

Returns

bool

True if the file was successfully created; otherwise, false

Type Parameters

TEntity

The entity type to export

ToCsvFile<TEntity>(IEnumerable<TEntity>, string, CsvOptions)

Saves a collection of entities to a CSV file with custom CSV options. Property values are formatted according to configured output formatters.

public static bool ToCsvFile<TEntity>(this IEnumerable<TEntity> entities, string filePath, CsvOptions csvOptions)

Parameters

entities IEnumerable<TEntity>

The collection of entities to export

filePath string

The destination file path

csvOptions CsvOptions

Custom CSV formatting options

Returns

bool

True if the file was successfully created; otherwise, false

Type Parameters

TEntity

The entity type to export

ToDataTable(byte[])

Converts CSV byte data to a DataTable with default options.

public static DataTable ToDataTable(byte[] csvBytes)

Parameters

csvBytes byte[]

CSV data as byte array

Returns

DataTable

A DataTable populated with CSV data

ToDataTable(byte[], CsvOptions)

Converts CSV byte data to a DataTable with custom CSV options.

public static DataTable ToDataTable(byte[] csvBytes, CsvOptions csvOptions)

Parameters

csvBytes byte[]

CSV data as byte array

csvOptions CsvOptions

Custom CSV parsing options (encoding, separator, etc.)

Returns

DataTable

A DataTable populated with CSV data

ToDataTable(Stream)

Converts CSV stream data to a DataTable with default options.

public static DataTable ToDataTable(Stream stream)

Parameters

stream Stream

Stream containing CSV data

Returns

DataTable

A DataTable populated with CSV data

ToDataTable(Stream, CsvOptions)

Converts CSV stream data to a DataTable with custom CSV options. The first row is treated as column headers.

public static DataTable ToDataTable(Stream stream, CsvOptions csvOptions)

Parameters

stream Stream

Stream containing CSV data

csvOptions CsvOptions

Custom CSV parsing options

Returns

DataTable

A DataTable populated with CSV data

ToDataTable(string)

Converts CSV file data to a DataTable with default options.

public static DataTable ToDataTable(string filePath)

Parameters

filePath string

Path to the CSV file

Returns

DataTable

A DataTable populated with CSV data

Exceptions

ArgumentNullException

Thrown when filePath is null

ArgumentException

Thrown when the file does not exist

ToEntities<TEntity>(byte[], CsvOptions?)

Converts CSV byte data to a lazy-loaded sequence of strongly-typed entities.

public static IEnumerable<TEntity?> ToEntities<TEntity>(byte[] csvBytes, CsvOptions? csvOptions = null)

Parameters

csvBytes byte[]

CSV data as byte array

csvOptions CsvOptions

Optional custom CSV parsing options

Returns

IEnumerable<TEntity>

A lazy-loaded enumerable of entities

Type Parameters

TEntity

The entity type to map CSV data to

ToEntities<TEntity>(Stream, CsvOptions?)

Converts CSV stream data to a lazy-loaded sequence of strongly-typed entities. This method is memory-efficient for large CSV files.

public static IEnumerable<TEntity?> ToEntities<TEntity>(Stream csvStream, CsvOptions? csvOptions = null)

Parameters

csvStream Stream

Stream containing CSV data

csvOptions CsvOptions

Optional custom CSV parsing options

Returns

IEnumerable<TEntity>

A lazy-loaded enumerable of entities

Type Parameters

TEntity

The entity type to map CSV data to

ToEntities<TEntity>(string, CsvOptions?)

Converts CSV file data to a lazy-loaded sequence of strongly-typed entities. Use this method for large files to avoid loading all data into memory at once.

public static IEnumerable<TEntity?> ToEntities<TEntity>(string filePath, CsvOptions? csvOptions = null)

Parameters

filePath string

Path to the CSV file

csvOptions CsvOptions

Optional custom CSV parsing options

Returns

IEnumerable<TEntity>

A lazy-loaded enumerable of entities

Type Parameters

TEntity

The entity type to map CSV data to

Exceptions

ArgumentException

Thrown when the file does not exist

ToEntityList<TEntity>(byte[])

Converts CSV byte data to a strongly-typed entity list with default options.

public static List<TEntity?> ToEntityList<TEntity>(byte[] csvBytes)

Parameters

csvBytes byte[]

CSV data as byte array

Returns

List<TEntity>

A list of entities populated from CSV data

Type Parameters

TEntity

The entity type to map CSV data to

ToEntityList<TEntity>(byte[], CsvOptions)

Converts CSV byte data to a strongly-typed entity list with custom options.

public static List<TEntity?> ToEntityList<TEntity>(byte[] csvBytes, CsvOptions csvOptions)

Parameters

csvBytes byte[]

CSV data as byte array

csvOptions CsvOptions

Custom CSV parsing options

Returns

List<TEntity>

A list of entities populated from CSV data

Type Parameters

TEntity

The entity type to map CSV data to

ToEntityList<TEntity>(Stream)

Converts CSV stream data to a strongly-typed entity list with default options.

public static List<TEntity?> ToEntityList<TEntity>(Stream csvStream)

Parameters

csvStream Stream

Stream containing CSV data

Returns

List<TEntity>

A list of entities populated from CSV data

Type Parameters

TEntity

The entity type to map CSV data to

ToEntityList<TEntity>(Stream, CsvOptions)

Converts CSV stream data to a strongly-typed entity list with custom options.

public static List<TEntity?> ToEntityList<TEntity>(Stream csvStream, CsvOptions csvOptions)

Parameters

csvStream Stream

Stream containing CSV data

csvOptions CsvOptions

Custom CSV parsing options

Returns

List<TEntity>

A list of entities populated from CSV data

Type Parameters

TEntity

The entity type to map CSV data to

ToEntityList<TEntity>(string)

Converts CSV file data to a strongly-typed entity list with default options.

public static List<TEntity?> ToEntityList<TEntity>(string filePath)

Parameters

filePath string

Path to the CSV file

Returns

List<TEntity>

A list of entities populated from CSV data

Type Parameters

TEntity

The entity type to map CSV data to

ToEntityList<TEntity>(string, CsvOptions)

Converts CSV file data to a strongly-typed entity list with custom options.

public static List<TEntity?> ToEntityList<TEntity>(string filePath, CsvOptions csvOptions)

Parameters

filePath string

Path to the CSV file

csvOptions CsvOptions

Custom CSV parsing options

Returns

List<TEntity>

A list of entities populated from CSV data

Type Parameters

TEntity

The entity type to map CSV data to

Exceptions

ArgumentException

Thrown when the file does not exist