BenBurgers.Text.Csv 1.0.0

CSV

This package provides features for reading from and writing to CSV data.

CSV Reader

The CSV Reader can read CSV data from a data stream. The simple implementation only returns an array of raw data, whereas the generic implementation maps data to a predefined CSV record.

Raw

Construction

The simple CSV Reader can easily be setup like so:

using BenBurgers.Text.Csv;

var options = new CsvOptions(Delimiter: ';');
using var reader = new CsvReader(stream, options);

It uses the delimiter character ; for separating column values. The CsvOptions also has a property that indicates whether the CSV data source has a header line with column names.

using BenBurgers.Text.Csv;

var options = new CsvOptions(Delimiter: ';', HasHeaderLine: true);
using var reader = new CsvReader(stream, options);

In this case the reader automatically reads the first line and sets the ColumnNames property with the names read on the first line. Additionally, a CodePage may be configured to identify the encoding of the file. This defaults to UTF-8.

Reading data

The raw values may be read line by line:

var rawValues = await reader.ReadLineAsync(); // returns IReadOnlyList<string>

An optional CancellationToken may be passed as a parameter.

Generic

The generic CSV Reader has an additional option to map CSV raw data. The BenBurgers.Text.Csv.Mapping namespace has mapping features.

There are two ways (one is extended) for mapping:

Converter

The converter gets a function that receives the raw data as strings and outputs the CSV record. The implementer has full control over how the raw values are converted to a record.

var converterMapping = new CsvConverterMapping<MyCsvRecord>(rawValues => new MyCsvRecord(DoSomething(rawValues[0]), DoSomething2(rawValues[1])));
var options = new CsvOptions<MyCsvRecord>(converterMapping);
using var reader = new CsvReader(stream, options);

Header

The CSV data has a header line with column names. These names are then used to infer to which property or constructor parameter the values will be mapped.

var headerMapping =
	new CsvHeaderMapping<MyCsvRecord>(
		rawValues => new(
			rawValues[nameof(MyCsvRecord.SomeProperty)],
			DoSomething(rawValues[nameof(MyCsvRecord.AnotherProperty)])),
		new Dictionary<string, Func<MyCsvRecord, string>>
		{
			{ nameof(MyCsvRecord.SomeProperty), m => m.SomeProperty },
			{ nameof(MyCsvRecord.AnotherProperty), m => DoSomething(m.AnotherProperty) }
		});
var options = new CsvOptions<MyCsvRecord>(headerMapping);
using var reader = new CsvReader(stream, options);

This approach presumes the CSV data has a header line. A specialization is a mapping that uses reflection to automatically determine which column maps to which property or constructor parameter.

var headerTypeMapping = new CsvHeaderTypeMapping<MyCsvRecord>();
var options = new CsvOptions<MyCsvRecord>(headerTypeMapping);
using var reader = new CsvReader(stream, options);

An optional TypeConverter may be passed to the CsvHeaderTypeMapping<>'s constructor for converting properties' and constructor parameters' values to the raw values and vice versa.

CSV Writer

Conversely, the CSV Writer accepts a stream and configuration options as well.

Raw

var options = new CsvOptions();
using var writer = new CsvWriter(stream, options);
await writer.WriteLineAsync(new [] { "Value1", "123" });

Generic

var options = new CsvOptions<MyCsvRecord>(mapping);
using var writer = new CsvWriter<MyCsvRecord>(stream, options);
var record = new MyCsvRecord("Value1", 123);
await writer.WriteLineAsync(record);