👁 Image
OfficeIMO.CSV 0.1.46

OfficeIMO.CSV - fluent CSV document model

👁 nuget version
👁 nuget downloads

OfficeIMO.CSV is a fluent, strongly typed CSV document model aligned with the OfficeIMO ecosystem. It supports in-memory transforms, streaming reads, schemas, validation, typed mapping, and AOT-friendly explicit selectors.

Install

dotnet add package OfficeIMO.CSV

Quick start

using OfficeIMO.CSV;
using System.Globalization;

new CsvDocument()
 .WithDelimiter(';')
 .WithCulture(CultureInfo.InvariantCulture)
 .WithHeader("Name", "Age", "City")
 .AddRow("Przemek", 36, "Mikolow")
 .AddRow("Dominika", 30, "Mikolow")
 .AddColumn("Bucket", row => row.AsInt32("Age") >= 35 ? "Senior" : "Regular")
 .SortBy("Age")
 .Filter(row => row.AsString("City") == "Mikolow")
 .Save("people.csv", new CsvSaveOptions {
 Delimiter = ';',
 IncludeHeader = true,
 NewLine = "\n"
 });

What it does

• Keeps headers and rows as a first-class document model instead of ad hoc string arrays.
• Loads from files, streams, or text and saves through configurable delimiter, culture, encoding, and newline options.
• Supports AddRow, AddColumn, RemoveColumn, SortBy, Filter, and Transform.
• Provides schema validation with required columns, typed columns, defaults, and custom rules.
• Maps rows to typed objects with explicit no-reflection mapping.
• Supports streaming mode for large files and explicit materialization when transforms are needed.

Schema example

var document = CsvDocument.Load("input.csv")
 .EnsureSchema(schema => schema
 .Column("Id").AsInt32().Required()
 .Column("Name").AsString().Required()
 .Column("Age").AsInt32().Optional())
 .ValidateOrThrow();

Collect validation errors without throwing when an import pipeline should report all bad rows:

var document = CsvDocument.Load("input.csv")
 .EnsureSchema(schema => schema
 .Column("Id").AsInt32().Required()
 .Column("Name").AsString().Required()
 .Column("Age").AsInt32().Optional()
 .Column("Active").AsBoolean().WithDefault(true));

document.Validate(out var errors);
foreach (var error in errors) {
 Console.WriteLine($"{error.RowIndex}:{error.ColumnName} - {error.Message}");
}

Typed mapping

Mapping is explicit and delegate-based, so it stays predictable for trimming and NativeAOT-sensitive applications.

using OfficeIMO.CSV;

List<Person> people = CsvDocument.Load("people.csv")
 .Map<Person>(map => map
 .FromColumn<int>("Id", (person, value) => {
 person.Id = value;
 return person;
 })
 .FromColumn<string>("Name", (person, value) => {
 person.Name = value;
 return person;
 })
 .FromColumn<int>("Age", (person, value) => {
 person.Age = value;
 return person;
 })
 .FromColumn<string>("City", (person, value) => {
 person.City = value;
 return person;
 }))
 .ToList();

public sealed class Person {
 public int Id { get; set; }
 public string Name { get; set; } = "";
 public int Age { get; set; }
 public string City { get; set; } = "";
}

For immutable models, return a new instance from each assignment:

using OfficeIMO.CSV;

var people = CsvDocument.Load("people.csv")
 .Map<PersonRecord>(map => map
 .FromColumn<int>("Id", (person, value) => person with { Id = value })
 .FromColumn<string>("Name", (person, value) => person with { Name = value }))
 .ToList();

public sealed record PersonRecord {
 public int Id { get; init; }
 public string Name { get; init; } = "";
}

Streaming and materializing

Use streaming mode when the caller only needs forward-only row processing.

foreach (var row in CsvDocument.Load("large.csv", new CsvLoadOptions {
 Mode = CsvLoadMode.Stream,
 HasHeaderRow = true,
 TrimWhitespace = true
}).AsEnumerable()) {
 int id = row.AsInt32("Id");
 string? status = row.AsString("Status");
 Console.WriteLine($"{id}: {status}");
}

Transforms such as SortBy, Filter, and AddColumn require in-memory mode. Materialize deliberately when that is the desired tradeoff:

var transformed = CsvDocument.Load("large.csv", new CsvLoadOptions {
 Mode = CsvLoadMode.Stream
 })
 .Materialize()
 .AddColumn("ImportedUtc", _ => DateTime.UtcNow)
 .Filter(row => row.AsString("Status") == "Ready")
 .SortBy(row => row.AsInt32("Id"));

transformed.Save("ready.csv");

Objects and ad hoc data

FromObjects is useful for small exports from anonymous objects, DTOs, or dictionaries:

var rows = new[] {
 new { Name = "Alpha", Count = 10, Active = true },
 new { Name = "Beta", Count = 20, Active = false }
};

CsvDocument.FromObjects(rows)
 .Save("summary.csv");

Parse text when a service receives CSV payloads without a temporary file:

string payload = "Name,Amount\nAlpha,10\nBeta,20";

var document = CsvDocument.Parse(payload)
 .AddColumn("Currency", _ => "EUR");

string normalized = document.ToString(new CsvSaveOptions {
 Delimiter = ',',
 IncludeHeader = true
});

Boundaries

• This package owns CSV parsing, writing, transforms, and validation.
• Reader integration belongs in OfficeIMO.Reader.Csv.
• Excel workbook behavior belongs in OfficeIMO.Excel.

Targets and license

• Targets: netstandard2.0, net8.0, net10.0, net472.
• License: MIT.
• Repository: EvotecIT/OfficeIMO