Shane32.CsvLinq 1.0.1

Shane32.CsvLinq

CsvLinq maps a single CSV file to a strongly typed list of row models. You define a context by deriving from CsvContext<TModel> and configuring the model once in OnModelCreating; the context then loads CSV data from a file or stream into List<TModel>, or saves a list back to a file or stream.

The library targets netstandard2.0 and has no runtime package dependencies.

Basic usage

public class InvoiceLine
{
    public DateTime Date { get; set; }
    public int Quantity { get; set; }
    public string Description { get; set; }
    public decimal Amount { get; set; }
    public string Notes { get; set; }
}

public class InvoiceLineCsv : CsvContext<InvoiceLine>
{
    protected override void OnModelCreating(CsvModelBuilder<InvoiceLine> builder)
    {
        builder.Column(x => x.Date);
        builder.Column(x => x.Quantity, "Qty");
        builder.Column(x => x.Description)
            .AlternateName("Desc");
        builder.Column(x => x.Amount);
        builder.Column(x => x.Notes)
            .Optional();

        builder.SkipEmptyRows();
    }
}

Read and write data directly:

var csv = new InvoiceLineCsv();

List<InvoiceLine> rows = csv.Load("invoice.csv");

rows.Add(new InvoiceLine {
    Date = DateTime.Today,
    Quantity = 2,
    Description = "Widgets",
    Amount = 12.50m
});

csv.Save("invoice-out.csv", rows);

Async file and stream APIs are also available:

var rows = await csv.LoadAsync("invoice.csv");
await csv.SaveAsync("invoice-out.csv", rows);

Configuration

CsvModelBuilder<TModel> and CsvColumnBuilder<TModel, TValue> are fluent builders. Configure your mappings inside OnModelCreating, then let CsvContext<TModel> handle load/save operations.

CsvModelBuilder<TModel> methods

CsvColumnBuilder<TModel, TValue> methods

Columns are required by default. Use .Optional() when a header may be missing or a field may be blank. Header matching is case-insensitive and trims surrounding whitespace, and alternate names can be defined for compatibility with older exports.

For string columns, blank fields deserialize according to the mapped member's nullable-reference annotation on supported target frameworks: string? receives null, while string receives string.Empty. When nullability metadata is not available, strings are treated as nullable. Use .Nullable() or .Nullable(false) to override the inferred behavior.

Default serializers/deserializers support these types and formats:

Per-column serialization can be customized:

builder.Column(x => x.Quantity)
    .Deserialize(value => int.Parse(value.Substring(2)))
    .Serialize(value => "Q-" + value);

Type-wide formatters apply to every configured column of that type:

builder.Format<decimal>(
    value => decimal.Parse(value.TrimStart('$'), CultureInfo.InvariantCulture),
    value => "$" + value.ToString("0.00", CultureInfo.InvariantCulture));

CSV output options can be configured directly on the model builder:

builder.LineEnding("\r\n")
    .EndsWithNewLine(true)
    .LineEndingsInStrings(CsvLineEndingHandling.Replace)
    .LineEndingReplacement(" ");

Advanced customization

For advanced scenarios, CsvContext<TModel> exposes protected methods you can override:

Most applications only need OnModelCreating; override the other methods when you need custom parsing/writing pipelines or conversion behavior.

Credits

Glory to Jehovah, Lord of Lords and King of Kings, creator of Heaven and Earth, who through his Son Jesus Christ, has reedemed me to become a child of God. -Shane32