NHSISL.CsvHelperClient 2.0.0

NHSISL - CsvHelperClient

Introduction

CsvHelperClient is a .NET, Standard-compliant wrapper around the popular CsvHelper library. It exposes a clean, async-first API for mapping CSV data to strongly typed .NET objects and vice versa, with built-in support for custom field mappings, optional headers, and trailing-comma control.

Features

• ✅ Stream-based — works directly with Stream, keeping memory usage low even for large files
• ✅ Fully async — IAsyncEnumerable<T> for reading, ValueTask for writing
• ✅ Header control — include or omit header rows when reading and writing
• ✅ Custom field mappings — map CSV column indices to object properties by name
• ✅ Trailing comma support — optionally append a trailing comma to each row
• ✅ Cancellation support — all methods accept a CancellationToken
• ✅ Structured exceptions — clear validation and dependency exceptions for reliable error handling

Installation

Install the package from NuGet:

dotnet add package NHSISL.CsvHelperClient

Or search for NHSISL.CsvHelperClient in the Visual Studio NuGet Package Manager.

Quick Start

1. Define your model

public class Car
{
    public string Make { get; set; }
    public string Model { get; set; }
    public int Year { get; set; }
    public string Color { get; set; }
}

2. Instantiate the client

CsvClient implements IAsyncDisposable, so use it inside an await using block or manage its lifetime via dependency injection.

await using var csvClient = new CsvClient();

Reading CSV Data

Map CSV to objects (with header row)

When your CSV file contains a header row whose column names match your model's property names, simply pass hasHeaderRecord: true:

string csv = """
    Make,Model,Year,Color
    Toyota,Corolla,2022,White
    Ford,Focus,2021,Blue
    """;

byte[] csvBytes = Encoding.UTF8.GetBytes(csv);
using var inputStream = new MemoryStream(csvBytes);

await using var csvClient = new CsvClient();

await foreach (Car car in csvClient.MapCsvToObjectAsync<Car>(
    data: inputStream,
    hasHeaderRecord: true))
{
    Console.WriteLine($"{car.Year} {car.Make} {car.Model} ({car.Color})");
}

Map CSV to objects (no header, with custom field mappings)

When there is no header row, or the column order differs from your model, supply a fieldMappings dictionary that maps each property name to its zero-based column index:

// CSV columns: Color(0), Year(1), Model(2), Make(3)
string csv = """
    White,2022,Corolla,Toyota
    Blue,2021,Focus,Ford
    """;

byte[] csvBytes = Encoding.UTF8.GetBytes(csv);
using var inputStream = new MemoryStream(csvBytes);

var fieldMappings = new Dictionary<string, int>
{
    { nameof(Car.Make),  3 },
    { nameof(Car.Model), 2 },
    { nameof(Car.Year),  1 },
    { nameof(Car.Color), 0 }
};

await using var csvClient = new CsvClient();

await foreach (Car car in csvClient.MapCsvToObjectAsync<Car>(
    data: inputStream,
    hasHeaderRecord: false,
    fieldMappings: fieldMappings))
{
    Console.WriteLine($"{car.Year} {car.Make} {car.Model} ({car.Color})");
}

Writing CSV Data

Map objects to CSV (with header row)

var cars = new List<Car>
{
    new Car { Make = "Toyota", Model = "Corolla", Year = 2022, Color = "White" },
    new Car { Make = "Ford",   Model = "Focus",   Year = 2021, Color = "Blue"  }
};

using var outputStream = new MemoryStream();

await using var csvClient = new CsvClient();

await csvClient.MapObjectToCsvAsync(
    @object: cars,
    outputStream: outputStream,
    addHeaderRecord: true);

string csvOutput = Encoding.UTF8.GetString(outputStream.ToArray());
Console.WriteLine(csvOutput);
// Make,Model,Year,Color
// Toyota,Corolla,2022,White
// Ford,Focus,2021,Blue

Map objects to CSV (no header)

await csvClient.MapObjectToCsvAsync(
    @object: cars,
    outputStream: outputStream,
    addHeaderRecord: false);

Map objects to CSV with custom column order

Use fieldMappings to control the column order. Each entry maps a property name to its zero-based output column index:

// Output order: Color(0), Year(1), Model(2), Make(3)
var fieldMappings = new Dictionary<string, int>
{
    { nameof(Car.Make),  3 },
    { nameof(Car.Model), 2 },
    { nameof(Car.Year),  1 },
    { nameof(Car.Color), 0 }
};

await csvClient.MapObjectToCsvAsync(
    @object: cars,
    outputStream: outputStream,
    addHeaderRecord: false,
    fieldMappings: fieldMappings);

Map objects to CSV with a trailing comma

Some downstream systems expect every row to end with a comma. Enable this with shouldAddTrailingComma:

await csvClient.MapObjectToCsvAsync(
    @object: cars,
    outputStream: outputStream,
    addHeaderRecord: true,
    shouldAddTrailingComma: true);

API Reference

ICsvClient

MapCsvToObjectAsync parameters

MapObjectToCsvAsync parameters

Error Handling

CsvHelperClient surfaces errors through a structured exception hierarchy so you can handle specific failure modes precisely:

Example:

try
{
    await foreach (var car in csvClient.MapCsvToObjectAsync<Car>(
        data: inputStream,
        hasHeaderRecord: true))
    {
        Console.WriteLine(car.Make);
    }
}
catch (CsvHelperClientValidationException ex)
{
    Console.WriteLine($"Validation error: {ex.Message}");
}
catch (CsvHelperClientDependencyException ex)
{
    Console.WriteLine($"Dependency error: {ex.Message}");
}

How to Contribute

If you want to contribute to this project, please review the following documents to gain an understanding of the patterns and practices used in building this package:

• The Standard
• C# Coding Standard
• The Team Standard

To report a bug, please open a GitHub issue with as much detail as possible. If you'd like to contribute, feel free to pick up any open issue and submit a pull request with your changes.