BenBurgers.Text.Csv 1.1.0

dotnet add package BenBurgers.Text.Csv --version 1.1.0
NuGet\Install-Package BenBurgers.Text.Csv -Version 1.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BenBurgers.Text.Csv" Version="1.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BenBurgers.Text.Csv --version 1.1.0
#r "nuget: BenBurgers.Text.Csv, 1.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install BenBurgers.Text.Csv as a Cake Addin
#addin nuget:?package=BenBurgers.Text.Csv&version=1.1.0

// Install BenBurgers.Text.Csv as a Cake Tool
#tool nuget:?package=BenBurgers.Text.Csv&version=1.1.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.

using BenBurgers.Text.Csv;

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);

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.

using BenBurgers.Text.Csv;

var headerMapping =
	new CsvHeaderMapping<MyCsvRecord>(
		new[] { "SomeProperty", "AnotherProperty" },
		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.

using BenBurgers.Text.Csv;

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

using BenBurgers.Text.Csv;

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

Generic

using BenBurgers.Text.Csv;

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

CSV Stream

A CSV Stream is a combination of a reader and a writer. It also provides additional functionality such as looking up a particular line or inserting/appending a line to CSV data.

using BenBurgers.Text.Csv;

var options new CsvOptions();
using var stream = new CsvStream(stream, options);
stream.GoTo(5L); // Go to the 6th line (zero-based)
var values = stream.ReadLine(); // Returns the CSV values at the 6th line.
stream.InsertLine(3L, new[] { "foo", "123", "bar" }); // Inserts the specified values at the 4th line (zero-based).
stream.AppendLine(new[] { "bar", "321", "foo" }); // Appends the specified values at the end of the stream.

The generic CSV Stream has similar features to the generic reader and generic writer and uses the same mapping options.

CSV Stream Factory

A CSV Stream Factory facilitates creating CSV streams from various sources.

  • A FileInfo.
  • An HttpClient.
  • A Stream.
  • A file located at a particular path.
using BenBurgers.Text.Csv;

var options = new CsvOptions();
var factory = new CsvStreamFactory(options);
using var csvStream = factory.FromFile("C:\\foo\\bar.csv");
using BenBurgers.Text.Csv;

var options = new CsvOptions();
var factory = new CsvStreamFactory(options);
using var memoryStream = new MemoryStream();
using var csvStream = factory.From(memoryStream);
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.
  • net7.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on BenBurgers.Text.Csv:

Package Downloads
BenBurgers.InternationalStandards.Iso.IO

Input/Output for international standards as adopted by the International Organization for Standardization (ISO). This may include country codes, language codes and more.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.0 365 12/19/2022
1.0.0 279 12/7/2022

Version 1.1.0
- CsvStream.
- CsvStreamFactory.
- CSV attributes for optional custom type mapping.
- CSV generic mappings have a dynamic column order.

Version 1.0.0
- CsvReader.
- CsvWriter.
- Mapping options.