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

Methods

Create<T>(CsvReader)

Added in v34.0.0static
public static CsvRecordMapper<T> Create<T>(CsvReader reader)

Creates a mapper of T for the header of reader, which is read now if it has not been yet.

Type parameters

T
The type of the records.

Parameters

readerCsvReader
The reader whose header names the columns.

Returns

CsvRecordMapper<T>
A mapper that reads records of reader, and of any reader with the same columns.

Exceptions

ArgumentNullException
reader is null.
InvalidOperationException
T is not a CsvRecordAttribute type, or its nested mappers lead back to their own type without end (records nest at most 64 deep).
KeyNotFoundException
The header lacks a column that T requires, or the input has no header and a required member has no column index.

View source

Create<T>(CsvReader, string)

Added in v34.0.0static
public static CsvRecordMapper<T> Create<T>(CsvReader reader, string columnPrefix)

Creates a mapper of T for the header of reader that puts columnPrefix in front of the header names it looks up. The header is read now if it has not been yet.

Type parameters

T
The type of the records.

Parameters

readerCsvReader
The reader whose header names the columns.
columnPrefixstring
The text in front of each header name, such as "Ship "; "" for none.

Returns

CsvRecordMapper<T>
A mapper that reads records of reader, and of any reader with the same columns.

Exceptions

ArgumentNullException
reader or columnPrefix is null.
InvalidOperationException
T has no mapper, or its mapper does not support column prefixes and columnPrefix is not empty, or its nested mappers lead back to their own type without end (records nest at most 64 deep).
KeyNotFoundException
The header lacks a column that T requires, or the input has no header and a required member has no column index.

View source

public static CsvRecordMapper<T> CreateProjection<T>(CsvReader reader, IEnumerable<string> members)

Creates a mapper of T for the header of reader that reads only members, so the columns of the others are neither looked up nor parsed. The other members get their defaults (constructor parameters their default values; members that are not set by the constructor or an init accessor keep their own initial values), their columns may be missing from the header, and their CsvValidateAttribute checks do not run. The header is read now if it has not been yet.

Type parameters

T
A CsvRecordAttribute type with projections (see TryGetMembers).

Parameters

readerCsvReader
The reader whose header names the columns.
membersIEnumerable<string>
The names of the members to read (CsvRecordMember.Name), in any order.

Returns

CsvRecordMapper<T>
A mapper that reads the selected members of records of reader, and of any reader with the same columns; the full mapper when every member is selected.

Exceptions

ArgumentNullException
reader or members is null.
ArgumentException
members names a member that the mapper does not read.
InvalidOperationException
T has no mapper, or its nested mappers lead back to their own type without end (records nest at most 64 deep).
NotSupportedException
T has no projections.
KeyNotFoundException
The header lacks a column that a selected member requires, or the input has no header and a selected required member has no column index.

View source

GetFieldWidths<T>()

Added in v34.0.0static
public static IReadOnlyList<int> GetFieldWidths<T>()

Gets the fixed-width layout of T: the CsvColumnAttribute.Width of each column, ordered by CsvColumnAttribute.Index, for CsvReaderOptions.FieldWidths and CsvWriterOptions.FieldWidths.

Type parameters

T
A CsvRecordAttribute type whose members have widths.

Returns

IReadOnlyList<int>
The widths of the columns, in characters.

Exceptions

InvalidOperationException
T has no mapper, or its members have no widths.

View source

public static void Register<T>(Func<CsvReader, CsvRecordMapper<T>> factory)

Registers the mapper factory of T, such as a hand-written CsvRecordMapper<T>. A later registration for the same type replaces an earlier one.

Type parameters

T
The type of the records.

Parameters

factoryFunc<CsvReader, CsvRecordMapper<T>>
Creates a mapper for the header of the given reader.

Exceptions

ArgumentNullException
factory is null.

Remarks

The mapper cannot be used as a nested record with a CsvColumnAttribute.Prefix; register a factory that takes the prefix (Register<T>(Func<CsvReader, string, CsvRecordMapper<T>>, IReadOnlyList<int>)) for that.

View source

public static void Register<T>(Func<CsvReader, string, CsvRecordMapper<T>> factory, IReadOnlyList<int>? fieldWidths = null)

Registers the mapper factory of T, and its fixed-width layout. Code generated for CsvRecordAttribute types calls this when their assembly is loaded. A later registration for the same type replaces an earlier one.

Type parameters

T
The type of the records.

Parameters

factoryFunc<CsvReader, string, CsvRecordMapper<T>>
Creates a mapper for the header of the given reader, which puts the given text in front of the header names it looks up (CsvRecordMapper<T>.ColumnPrefix).
fieldWidthsIReadOnlyList<int>?
The widths of the columns, which GetFieldWidths returns, or null when the type has no fixed-width layout.

Exceptions

ArgumentNullException
factory is null.

View source

public static void Register<T>(Func<CsvReader, string, CsvRecordMapper<T>> factory, IReadOnlyList<int>? fieldWidths, Func<IReadOnlyList<CsvRecordMember>> members, Func<CsvReader, string, bool[], CsvRecordMapper<T>> projection)

Registers the mapper factory of T and its fixed-width layout, with the description of the members that its mappers read and the factory of its projections: mappers that read only some of the members, so that the columns of the others are neither looked up nor parsed (CsvHelper.Linq reads only the members that a query uses). Code generated for CsvRecordAttribute types calls this when their assembly is loaded, if the assembly references CsvHelper.Linq or has CsvRecordProjectionsAttribute. A later registration for the same type replaces an earlier one.

Type parameters

T
The type of the records.

Parameters

factoryFunc<CsvReader, string, CsvRecordMapper<T>>
Creates a mapper for the header of the given reader, which puts the given text in front of the header names it looks up (CsvRecordMapper<T>.ColumnPrefix).
fieldWidthsIReadOnlyList<int>?
The widths of the columns, which GetFieldWidths returns, or null when the type has no fixed-width layout.
membersFunc<IReadOnlyList<CsvRecordMember>>
Describes the members that the mappers read, in the order of the flags that projection takes. It is called once, when the members are first needed.
projectionFunc<CsvReader, string, bool[], CsvRecordMapper<T>>
Creates a mapper for the header of the given reader, with the given column prefix, that reads only the members whose flag is set: one flag for each member that members describes, in that order. The mapper must not keep the array. The other members get their defaults, and their columns may be missing.

Exceptions

ArgumentNullException
factory, members or projection is null.

View source

public static void RegisterOptions<T>(Func<CsvReaderOptions> readerOptions, Func<CsvWriterOptions> writerOptions)

Registers the options of the CsvOptionsAttribute of T, which CsvReaderOptions.For and CsvWriterOptions.For return. Code generated for the attribute calls this when the type's assembly is loaded. A later registration for the same type replaces an earlier one.

Type parameters

T
The type of the records.

Parameters

readerOptionsFunc<CsvReaderOptions>
Creates the reader options, on the first call of CsvReaderOptions.For.
writerOptionsFunc<CsvWriterOptions>
Creates the writer options, on the first call of CsvWriterOptions.For.

Exceptions

ArgumentNullException
readerOptions or writerOptions is null.

View source

public static bool TryGetMembers<T>(out IReadOnlyList<CsvRecordMember> members)

Gets the members of T that its generated mapper reads, when projections are generated for it (its assembly references CsvHelper.Linq or has CsvRecordProjectionsAttribute).

Type parameters

T
The type of the records.

Parameters

membersIReadOnlyList<CsvRecordMember>
The members, constructor parameters first, in the order the mapper reads them; empty when the method returns false.

Returns

bool
true when the members are known, so that CreateProjection can select them; false when T has no mapper, a hand-written mapper, no projections, or is a dynamic record type.

View source