Building a dependable CSV parser with modern C#

CSV looks simple until a field contains a comma, a quotation mark, a line break, or an unexpected character encoding. A parser that works for a small sample can fail when it receives an export from accounting software, a spreadsheet edited in Melbourne, or a large data file uploaded overnight in Sydney.

Modern C# gives you useful tools for solving this problem cleanly. Raw string literals make test fixtures readable, while C# 12 features such as collection expressions, primary constructors, improved pattern matching, and span-friendly APIs help reduce ceremony around the parser itself.

The key is to treat CSV as a small language rather than as text that can be safely split with string.Split(','). The parser must track whether it is inside quoted content, preserve embedded commas and newlines, and report malformed input with enough context for an application team to fix the source file.

This example builds a reusable, UTF-8-friendly parser for .NET 8. It focuses on correctness and clear design, with practical details that matter in Australian systems, including dd/MM/yyyy dates, GST-related exports, and postcodes such as 0800 whose leading zero must be preserved.

Why splitting on commas fails

A CSV record can contain commas inside quoted fields. For example, an Australian customer address might be written as "14 George Street, The Rocks, NSW". Splitting the line at every comma would incorrectly turn one address into several columns.

Quotation marks also have a defined escaping rule. A literal quotation mark inside a quoted field is represented by two quotation marks:

"Customer said ""call after lunch"""

The resulting field value should be:

Customer said "call after lunch"

A record may span multiple physical lines as well. A notes field containing a line break is valid when the entire field is quoted. This is common in CRM exports and support systems where staff add several lines of notes during the arvo.

A useful parser therefore needs three states:

• It is reading an ordinary field.
• It is reading a quoted field.
• It has just seen a quotation mark inside a quoted field and must decide whether it is escaped or closing.

That small state machine is easier to test and maintain than a collection of regular expressions.

Modelling parser results

A parser should make its output explicit. Returning List<string[]> is convenient, but it gives callers no indication of whether a row was malformed or whether columns have consistent names. A small record type provides a stronger boundary between parsing and application logic.

public sealed record CsvRow(
    int LineNumber,
    IReadOnlyList<string> Fields);

public sealed record CsvParseError(
    int LineNumber,
    string Message);

The LineNumber value refers to the physical line where the parser detected the issue. A quoted field can occupy several lines, so production systems may also track the starting line of the record. That refinement makes diagnostics more precise for large imports.

For a first implementation, expose rows as an iterator. This allows callers to process a large file without loading the entire export into memory:

public sealed record CsvDocument(
    IReadOnlyList<string> Headers,
    IEnumerable<CsvRow> Rows);

If the input is a sales export, the application can map each row into a typed model after parsing. Keep conversion separate from tokenisation. The parser should understand commas and quotes; a mapper should understand dates, decimal amounts, tax codes, and business rules.

Using raw strings for readable test data

Raw string literals arrived in C# 11, so they are available when a C# 12 project targets a suitable .NET SDK. They are especially valuable for CSV tests because ordinary string literals require escaped quotation marks and newline characters.

const string CsvSample = """
    CustomerId,Name,Postcode,Notes
    1001,"Nguyen, Minh",3000,"Prefers email"
    1002,"O'Connor, Siobhan",0800,"Call after 3pm"
    1003,"Taylor, Alex",2000,"Address confirmed
    during the arvo"
    """;

The content is visually close to the input file. The 0800 postcode is intentionally kept as text. Converting it to an integer would turn it into 800, which is incorrect for a Northern Territory address.

Raw strings are also helpful when testing escaped quotation marks:

const string QuotedText = """
    Id,Comment
    7,"The customer said ""approved"""
    """;

For test data containing several quotation marks at the beginning or end of a line, increase the number of $ or quote characters used by the raw string delimiter. This avoids awkward escaping while keeping the fixture easy to review in source control.

Implementing the state machine

The parser can consume a TextReader, which supports files, memory streams, HTTP responses, and test strings. The implementation below reads one character at a time so it can recognise commas, line endings, and quoted content without making assumptions about physical lines.

public sealed class CsvParser
{
    private readonly TextReader _reader;

    public CsvParser(TextReader reader) => _reader = reader;

    public IEnumerable<IReadOnlyList<string>> ReadRows()
    {
        var fields = [];
        var field = new StringBuilder();
        var inQuotes = false;
        var sawAnyCharacter = false;

        while (_reader.Read() is int value && value >= 0)
        {
            sawAnyCharacter = true;
            var character = (char)value;

            if (inQuotes)
            {
                if (character == '"')
                {
                    if (_reader.Peek() == '"')
                    {
                        _reader.Read();
                        field.Append('"');
                    }
                    else
                    {
                        inQuotes = false;
                    }
                }
                else
                {
                    field.Append(character);
                }

                continue;
            }

            switch (character)
            {
                case '"':
                    if (field.Length != 0)
                        throw new FormatException("A quote appeared inside an unquoted field.");

                    inQuotes = true;
                    break;

                case ',':
                    fields.Add(field.ToString());
                    field.Clear();
                    break;

                case '\r':
                    if (_reader.Peek() == '\n')
                        _reader.Read();

                    fields.Add(field.ToString());
                    field.Clear();
                    yield return fields.ToArray();
                    fields.Clear();
                    break;

                case '\n':
                    fields.Add(field.ToString());
                    field.Clear();
                    yield return fields.ToArray();
                    fields.Clear();
                    break;

                default:
                    field.Append(character);
                    break;
            }
        }

        if (inQuotes)
            throw new FormatException("The file ended inside a quoted field.");

        if (sawAnyCharacter && (field.Length > 0 || fields.Count > 0))
        {
            fields.Add(field.ToString());
            yield return fields.ToArray();
        }
    }
}

This version handles CRLF files from Windows and LF files from Unix-like systems. It also supports commas and line breaks inside quoted fields. The fields = [] expression is a C# 12 collection expression; the compiler infers the target type from the field declaration.

A production parser should decide how to handle a trailing comma, empty files, blank records, and whitespace after a closing quote. Strict mode can reject invalid input immediately. Lenient mode can accept selected variations while recording warnings. Make that policy explicit instead of allowing accidental behaviour.

Adding headers and typed records

Many CSV exports use the first row as a header. Before mapping data, validate the header names and count. A file with CustomerId,Name,Postcode should not silently be processed as though it contained Id,Customer,Address.

public sealed record Customer(
    string CustomerId,
    string Name,
    string Postcode,
    string Notes);

static Customer ToCustomer(IReadOnlyList<string> row)
{
    if (row.Count != 4)
        throw new FormatException(
            $"Expected four columns but received {row.Count}.");

    return new Customer(
        CustomerId: row[0],
        Name: row[1],
        Postcode: row[2],
        Notes: row[3]);
}

Parsing values should use culture deliberately. Australian business exports commonly use dates such as 31/01/2025, while APIs often use ISO 8601 values such as 2025-01-31. Choose the expected format rather than relying on the machine’s current culture, particularly when a service runs in a different Azure region.

if (!DateOnly.TryParseExact(
        value,
        "dd/MM/yyyy",
        CultureInfo.GetCultureInfo("en-AU"),
        DateTimeStyles.None,
        out var invoiceDate))
{
    throw new FormatException($"Invalid Australian date: {value}");
}

For currency, use decimal, not double, and define whether values include GST. An ATO-facing workflow may need a tax-inclusive amount, a GST component, and a tax code as separate fields. Those decisions belong in the domain mapper, not in the low-level CSV reader.

Handling encoding, performance, and security

Most modern exports should be read as UTF-8. A UTF-8 file can start with a byte order mark, and the first header may contain that marker if it is handled incorrectly. When opening a file, specify the encoding and consider removing a leading \uFEFF from the first field.

using var stream = File.OpenRead("customers.csv");
using var reader = new StreamReader(
    stream,
    new UTF8Encoding(encoderShouldEmitUTF8Identifier: false),
    detectEncodingFromByteOrderMarks: true);

var parser = new CsvParser(reader);

For large files, stream rows and process them in batches. Avoid calling ReadToEnd() when an import may contain hundreds of megabytes. A streaming approach suits cloud workloads where an Azure Function or container receives an object from Blob Storage and sends validated records to a queue.

CSV can also be a security boundary. Spreadsheet applications may interpret values beginning with =, +, -, or @ as formulas when a generated CSV is opened. If your application exports user-controlled data, consider prefixing dangerous values or documenting a safe import workflow. Never assume that a file supplied by a trusted business partner is harmless.

If throughput becomes important, benchmark the parser with realistic data. StringBuilder is easy to understand, but a specialised implementation using spans or pooled buffers may reduce allocations. Optimise after measuring, because clarity is valuable in data-import code that must be supported across Australian business hours and regional deployments.

Testing malformed and real-world input

A parser test suite should include valid and invalid records. Raw strings make each case readable and keep the test focused on behaviour rather than escape sequences.

[Fact]
public void Preserves_commas_quotes_and_newlines()
{
    const string input = """
        Id,Description
        1,"One, two"
        2,"He said ""ready"""
        3,"First line
        Second line"
        """;

    using var reader = new StringReader(input);
    var rows = new CsvParser(reader).ReadRows().ToArray();

    Assert.Equal("One, two", rows[1][1]);
    Assert.Equal("He said \"ready\"", rows[2][1]);
    Assert.Equal("First line\nSecond line", rows[3][1]);
}

Also test an empty final field, a final record without a newline, CRLF input, a blank file, an unmatched quote, a quote appearing in unquoted data, and rows with inconsistent column counts. Property-based tests can generate random fields containing commas, quotes, and line endings, then verify that writing and reading produces the original values.

Use representative local data rather than only synthetic words. Include Australian postcodes such as 3000, 2000, and 0800; suburb names containing spaces; state abbreviations; and dates in the format used by the source system. A file produced in Perth may use LF line endings, while a Windows desktop export in Brisbane may use CRLF. Correctness should not depend on where the export was created.

Choosing an approach for your application

A handwritten parser is appropriate when you need a small dependency-free component, strict control over validation, or a focused learning implementation. A mature library is usually preferable when the application must support dialect options, unusual delimiters, comments, configurable quoting, or extensive error recovery.

The important design choice is to keep parsing, validation, and business mapping separate. That separation makes it easier to replace the parser, add a schema version, or route rejected rows to a review queue without changing the customer or invoice model.

A dependable C# 12 CSV workflow uses raw strings where they improve test readability, modern collection syntax where it reduces noise, and a deliberate state machine for the actual format rules. With explicit culture, encoding, schema validation, and streaming, the parser can handle everyday files from Australian operations as reliably as carefully designed API payloads.