CsvToolkit.Core 0.1.0

CsvToolkit.Core

<p align="center"> <img src="docs/assets/csvtoolkit-logo-dark.svg" alt="CsvToolkit.Core logo" width="760" /> </p>

CsvToolkit.Core is a high-performance CSV library for net10.0 focused on streaming and low allocations with Span<T>, Memory<T>, and ArrayPool<T>.

NuGet

Package name on NuGet.org: CsvToolkit.Core

dotnet add package CsvToolkit.Core --prerelease

Public API Overview

var options = new CsvOptions
{
    Delimiter = ',',
    HasHeader = true,
    Quote = '"',
    Escape = '"',
    TrimOptions = CsvTrimOptions.Trim,
    DetectColumnCount = true,
    ReadMode = CsvReadMode.Strict,
    CultureInfo = CultureInfo.InvariantCulture
};

using var reader = new CsvReader(streamOrTextReader, options);
using var writer = new CsvWriter(streamOrTextWriter, options);

// Row/field iteration
while (reader.TryReadRow(out var row))
{
    ReadOnlySpan<char> field = row.GetFieldSpan(0);
    string materialized = row.GetFieldString(1);
}

// Dictionary / dynamic
if (reader.TryReadDictionary(out var dict)) { /* header -> value */ }
if (reader.TryReadDynamic(out dynamic dyn)) { /* ExpandoObject */ }

// Strongly typed POCO
while (reader.TryReadRecord<MyRow>(out var record)) { }
writer.WriteHeader<MyRow>();
writer.WriteRecord(new MyRow());

// Async
await reader.ReadAsync();
await writer.WriteRecordAsync(new MyRow());

Features

• Read from TextReader and UTF-8 Stream
• Write to TextWriter and UTF-8 Stream
• Streaming row-by-row parser (no full-file load)
• Quoted fields, escaped quotes, delimiters inside quotes, CRLF/LF handling
• Header support, delimiter/quote/escape/newline configuration
• Trim options and strict/lenient error handling with callback context
• Field access as ReadOnlySpan<char> / ReadOnlyMemory<char>
• POCO mapping with:
  • Attributes: [CsvColumn], [CsvIndex], [CsvIgnore]
  • Fluent mapping: CsvMapRegistry.Register<T>(...)
• Type conversion:
  • primitives, enums, nullable, DateTime, DateOnly, TimeOnly, Guid
  • culture-aware parsing/formatting
  • custom converters (ICsvTypeConverter<T>)
• Async read/write entry points

Examples

Read POCOs

using var reader = new CsvReader(new StreamReader("people.csv"));
while (reader.TryReadRecord<Person>(out var person))
{
    Console.WriteLine(person.Name);
}

Write POCOs

using var writer = new CsvWriter(File.Create("people.csv"), new CsvOptions { NewLine = "\n" });
writer.WriteHeader<Person>();
foreach (var person in people)
{
    writer.WriteRecord(person);
}

Read Without String Allocations

while (reader.TryReadRow(out var row))
{
    ReadOnlySpan<char> id = row.GetFieldSpan(0);
    // parse directly from span
}

Fluent Mapping

var maps = new CsvMapRegistry();
maps.Register<Person>(map =>
{
    map.Map(x => x.Id).Name("person_id");
    map.Map(x => x.Name).Name("full_name");
});

Benchmarks

Benchmarks compare CsvToolkit.Core with CsvHelper for:

• Typed read (100k rows)
• Dictionary/dynamic read
• Typed write
• Semicolon + high quoting parse

Performance design notes:

• Performance Design Decisions

Run all benchmarks non-interactively:

dotnet run -c Release --project benchmarks/CsvToolkit.Benchmarks -- --filter "*"

Run one benchmark (faster while iterating):

dotnet run -c Release --project benchmarks/CsvToolkit.Benchmarks -- --filter "*CsvReadWriteBenchmarks.CsvToolkitCore_ReadTyped_Stream*"

Run from IDE:

• Project: benchmarks/CsvToolkit.Benchmarks
• Configuration: Release
• Program arguments: --filter "*"

If you run without --filter, BenchmarkDotNet enters interactive selection mode and waits for input.

Benchmark dataset generation is deterministic (Random seed-based) inside benchmark setup.

Latest Results

Run date: 2026-02-10
Machine: Apple M3 Pro
Runtime: .NET 10.0.0
Command: dotnet run -c Release --project benchmarks/CsvToolkit.Benchmarks -- --filter "*CsvReadWriteBenchmarks*"

Raw benchmark artifacts:

• BenchmarkDotNet.Artifacts/results/CsvToolkit.Benchmarks.CsvReadWriteBenchmarks-report-github.md
• BenchmarkDotNet.Artifacts/results/CsvToolkit.Benchmarks.CsvReadWriteBenchmarks-report.csv