OfficeIMO.CSV 3.6.1

OfficeIMO.CSV - fluent CSV document model

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

Create(path) associates a destination without writing it. Load(path) and LoadAsync(path) associate the source path, and successful path saves update it. Save() and SaveAsync() use that associated path. Stream saves keep the caller stream open and do not change the association. CsvDocument implements IDisposable; streaming enumerations own their individual readers.

using OfficeIMO.CSV;
using System.Globalization;

CsvDocument.Create()
    .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,
        FormulaInjectionPolicy = CsvFormulaInjectionPolicy.Escape,
        NewLine = "\n"
    });

Choose a read path

CsvLoadOptions controls Load, LoadAsync and Parse. CsvReaderOptions controls forward-only readers and reader projection. Both use the same delimiter, header, culture, encoding and input-limit property names and defaults. Reader options also include Schema, InferSchema, SchemaSampleRows and ParallelProcessing. OpenReader accepts a file path, Stream or TextReader and returns CsvDataReader, which derives from DbDataReader. OpenReaderAsync accepts a path or stream and returns Task<CsvDataReader> on .NET 8 and later.

For a memory-backed snapshot, use LoadAsync(...) followed by CreateDataReader(options), which also returns CsvDataReader. The incremental reader avoids buffering the complete file. For decoded text, pass a text reader:

using System.IO;
using OfficeIMO.CSV;

using var source = new StringReader("Id,Amount\n1,12.50\n");
using CsvDataReader reader = CsvDocument.OpenReader(source,
    new CsvReaderOptions { InferSchema = true });
while (reader.Read()) {
    Console.WriteLine(reader.GetDecimal(reader.GetOrdinal("Amount")));
}

CSV schema inference uses decimal for decimal values. Use an explicit Schema to select other column types.

Profiles, schema inference, explicit mapping, and parallel projection are optional settings on these paths, not separate document models.

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 single-character delimiters through Delimiter and multi-character delimiters through DelimiterText.
• Reads and writes compressed CSV files with extension-based detection for gzip, deflate, Brotli, and zlib.
• Can escape formula-like values during save when producing CSV files that people will open in spreadsheet applications.
• Handles real-world import details such as duplicate headers, generated blank headers, null tokens, static metadata columns, custom date formats, comments, W3C #Fields: headers, and mismatched row lengths.
• Provides cancellation, progress callbacks, parse-error collection, field-length limits, quote normalization, and string interning for import pipelines.
• Supports AddRow, AddColumn, RemoveColumn, SortBy, Filter, and Transform.
• Provides schema inference and schema validation with required columns, typed columns, defaults, and custom rules.
• Maps rows to typed objects with explicit no-reflection mapping.
• Provides forward-only DbDataReader access for large files without presenting a streaming document as an editable model.
• Provides ordered, bounded parallel projection for data readers and a span-backed transient-record path for decoded text on .NET 8 and later.
• Includes validated cross-library benchmark lanes with operating-system and run-mode provenance.

Performance without giving up the document model

OfficeIMO.CSV has dedicated field-span, reusable-row, streaming DbDataReader, projected-row and preformatted-text fast paths. The same package also keeps the features expected from a document and ingestion model: schema inference and validation, typed values, transforms, compressed files, malformed-input policy, formula-injection protection, progress, cancellation, and diagnostics.

Runtime, CPU, input shape, quoting, encoding, storage, warm-up, and consumer behavior all matter. Use the benchmark website for the current hash-pinned CSV/XLSX/XLSB comparison matrix. Missing operating-system or run-mode evidence remains visible rather than being inferred. The benchmark harness documents the exact commands, semantic output validation, allocation evidence, and publication path.

The opt-in tabular comparison suite also measures borrowed and materialized fields, typed and parallel parsing, UTF-8 row writing, and Arrow batches using validated, pinned workloads.

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}");
}

Use ConvertUsing when a column needs domain-specific conversion before it becomes a DataTable or IDataReader value:

var document = CsvDocument.Load("input.csv")
    .EnsureSchema(schema => schema
        .Column("Priority")
        .AsInt32()
        .ConvertUsing(value => string.Equals(Convert.ToString(value), "high", StringComparison.OrdinalIgnoreCase) ? 10 : 1));

DataTable table = document.ToDataTable();

Infer a schema from sampled rows when the incoming file should define the import contract:

var document = CsvDocument.Load("input.csv", new CsvLoadOptions {
    DateTimeFormats = new[] { "dd-MMM-yyyy" }
});

CsvSchema inferred = document.InferSchema(sampleSize: 1000);
document.EnsureInferredSchema()
    .ValidateOrThrow();

Policy profiles

Use a profile to select explicit defaults, then edit the returned options for the file's dialect. Each call creates independent options; existing constructors and APIs retain their current defaults. Use CreateReaderOptions(profile) for OpenReader and CreateLoadOptions(profile) for loaded documents.

CsvLoadOptions input = CsvProfiles.CreateLoadOptions(CsvProfile.Strict);
input.Delimiter = ';';
CsvDocument document = CsvDocument.Load("input.csv", input);

CsvSaveOptions output = CsvProfiles.CreateSaveOptions(CsvProfile.Spreadsheet);
document.Save("spreadsheet.csv", output);

Strict and Spreadsheet redact source values and custom-converter details in mapping failures. Parse failures throw by default; use CollectParseErrors, ParseErrors, MaxParseErrors and ParseErrorAction to configure collection or row skipping. Both profiles disable W3C header interpretation. All profiles retain the configured input-size and decompression limits.

Formula escaping applies to text and configured text tokens; typed negative numbers remain numeric. Escaping changes the exported text, so use a preserving profile when exact values are required. Load profiles retain formula-like input as text; they do not execute or rewrite it.

DetectEncodingFromByteOrderMarks = false keeps the configured encoding authoritative. Its own preamble is accepted; a different BOM does not switch the decoder. Text inputs are already decoded, and TextWriter output has no byte encoding. Profiles do not impose a culture-specific spreadsheet dialect; select the delimiter and culture explicitly when needed.

Typed mapping

For ordinary DTOs, RowsAs<T>() matches headers to writable properties without requiring a range or mapping builder. Matching is case-insensitive and ignores spaces and punctuation. OfficeIMO builds the writable-property plan once per model type and reuses compiled assignments when the runtime supports them:

List<Person> people = CsvDocument.Load("people.csv")
    .RowsAs<Person>()
    .ToList();

For a forward-only typed pipeline, project the existing DbDataReader surface. This avoids building a CsvDocument and keeps reader lifetime explicit:

using OfficeIMO.Data;

using CsvDataReader reader = CsvDocument.OpenReader("people.csv");
foreach (Person person in reader.RowsAs<Person>()) {
    Process(person);
}

Automatic, configured RowMapper<T> and factory mappings use the shared OfficeIMO.Data implementation on CSV and Excel readers and loaded documents. Loaded-document overloads accept format-specific options and a cancellationToken; the caller owns and disposes an explicitly opened reader.

On .NET 8 and later, ordinary unquoted UTF-8 file and seekable-stream readers also support the optional OfficeIMO.Data borrowed-text capability:

using OfficeIMO.Data;

using var reader = CsvDocument.OpenReader("people.csv");
while (reader.Read()) {
    if (reader.TryGetUtf8Text(0, out ReadOnlySpan<byte> text)) {
        ProcessUtf8Name(text);
    } else {
        ProcessName(reader.GetString(0));
    }
}

The successful span already contains normalized field text and requires no string allocation. Consume it before advancing, changing results, or closing the reader. Quoted fields, trimming, schema conversions, null markers, missing fields, and decoding replacements can return false; use ordinary getters in that case. A successful empty span represents an empty text field. Headerless streams use HasHeaderRow = false, retain the first data row, and derive generated column names and width from that record.

On .NET 8 and later, use RowsAsAsync<T>() when the reader should advance through DbDataReader.ReadAsync and observe cancellation between rows:

using OfficeIMO.CSV;
using OfficeIMO.Data;

await using CsvDataReader reader = await CsvDocument.OpenReaderAsync(
    "people.csv", cancellationToken: cancellationToken);

await foreach (Person person in reader.RowsAsAsync<Person>(cancellationToken)) {
    await ProcessAsync(person, cancellationToken);
}

OpenReaderAsync opens an incremental reader owned by the caller. Each ReadAsync advances through the source without loading a whole-file snapshot. Automatic, explicit RowMapper<T>, and factory mapping all have async overloads. For direct field access:

await using CsvDataReader reader = await CsvDocument.OpenReaderAsync(
    "people.csv",
    options: new CsvReaderOptions { Delimiter = ',' },
    cancellationToken: cancellationToken);

while (await reader.ReadAsync(cancellationToken)) {
    await ProcessNameAsync(reader.GetString(reader.GetOrdinal("Name")), cancellationToken);
}

Initialization reads the header or the first data record when headers are supplied or generated; schema inference additionally buffers at most SchemaSampleRows records and replays them during traversal. Temporary parsing memory follows the largest record, with fixed transport buffers. String interning can retain distinct field values. DetectDelimiter samples at most 64 Ki characters and 64 logical records, then replays the sampled prefix. If the bound cuts through a record or the meaningful header lies beyond it, detection uses complete samples or falls back to the configured delimiter. An explicit DelimiterText remains effective. ParallelProcessing captures input batches asynchronously and projects typed values on bounded workers in source order. Its prefetch can read up to MaxDegreeOfParallelism * BatchSize rows before exposing a batch; use sequential projection when first-row latency matters. Converters must be thread-safe. Compression, multiline records, header normalization, null tokens, static columns, and explicit or sampled schemas use the common CSV contracts. The stream overload consumes the current position and leaves the caller's stream open. The path overload owns its file. The opening cancellation token remains active until disposal; each ReadAsync also accepts an operation token. A cancelled or failed record cannot be resumed. Read and HasRows may perform synchronous I/O.

For a materialized snapshot, use LoadAsync followed by CreateDataReader:

var csv = await CsvDocument.LoadAsync("people.csv", cancellationToken: cancellationToken);
using DbDataReader reader = csv.CreateDataReader();

Use the explicit overload when assignments must be declared without reflection, including trimming- and NativeAOT-sensitive applications. This overload still requires T : new():

using OfficeIMO.CSV;

List<Person> people = CsvDocument.Load("people.csv")
    .RowsAs<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; } = "";
}

Use the three-argument FromColumn or FromColumns overload with RowMappingColumnOptions for an optional column, a column-specific culture, date/time formats, or a converter. Missing optional columns preserve the model's initialized value; present invalid values still fail. These controls share the same Core mapping owner across document, reader, async and parallel projections.

For a non-positional record with a public parameterless constructor, an assignment can return a new value from each step:

using OfficeIMO.CSV;

var people = CsvDocument.Load("people.csv")
    .RowsAs<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; } = "";
}

The mapper overload still requires a public parameterless constructor. For a positional record or another constructor-bound model, use the factory overload:

using OfficeIMO.CSV;

var people = CsvDocument.Load("people.csv")
    .RowsAs(factory: row => new PersonRecord(
        row.GetInt32(row.GetOrdinal("Id")),
        row.GetString(row.GetOrdinal("Name"))))
    .ToList();

public sealed record PersonRecord(int Id, string Name);

The factory receives the current IDataRecord; its typed getters use the CSV reader's configured culture and schema conversions. The same overload is available on DbDataReader and does not require T : new().

Ordered parallel mapping

Use RowsAsParallel<T>() when row conversion is substantial enough to repay worker scheduling. One producer reads the forward-only source, workers receive independent bounded batches, and results retain source order. MaxDegreeOfParallelism bounds concurrent batches. Leave BatchSize unset for the source's tuned bounded default; set it only when an application needs an explicit throughput-versus-working-set tradeoff:

using OfficeIMO.Data;

using CsvDataReader reader = CsvDocument.OpenReader("people.csv");
Person[] people = reader.RowsAsParallel<Person>(
    new ParallelRowMappingOptions {
        MaxDegreeOfParallelism = 8
    },
    cancellationToken).ToArray();

Loaded documents expose the same parallel mapping shapes, with separate parallelOptions, CSV options and cancellation:

using OfficeIMO.CSV;
using OfficeIMO.Data;

CsvDocument document = CsvDocument.Load("people.csv");
Person[] people = document.RowsAsParallel<Person>(
    parallelOptions: new ParallelRowMappingOptions { MaxDegreeOfParallelism = 8 },
    options: new CsvReaderOptions { InferSchema = true },
    cancellationToken: cancellationToken).ToArray();

The automatic, explicit RowMapper<T>, and Func<IDataRecord, T> projection shapes all have parallel overloads. Automatic and explicit mapping snapshot ordinary readers on the calling thread and map those bounded snapshots on workers. Factory mapping also snapshots ordinary readers when their field types are safe to copy, so its factory can run concurrently; readers with provider-owned or mutable field values keep their native calling-thread behavior. A degree of one always uses the corresponding sequential mapping contract. Concurrent factories must not mutate unprotected shared state or retain the transient IDataRecord.

On .NET 8 and later, decoded text can use the lower-overhead transient-record API. The builder resolves headers once, finds quote-safe record partitions, and maps bounded partition waves concurrently while retaining source order. Its returned factory receives span-backed fields directly from parser batches:

Person[] people = CsvDocument.ReadTextRowsAsParallel<Person>(
    csvText,
    header => {
        int id = header.GetOrdinal("Id");
        int name = header.GetOrdinal("Name");
        int age = header.GetOrdinal("Age");
        return row => new Person {
            Id = row.GetInt32(id),
            Name = row.GetString(name),
            Age = row.GetInt32(age)
        };
    },
    parallelOptions: new ParallelRowMappingOptions {
        MaxDegreeOfParallelism = 8
    },
    cancellationToken: cancellationToken).ToArray();

CsvRecord, and every span returned by it, is valid only during that factory call. Do not retain either one. Use CsvRecord.IsMissing(ordinal) when a short source row omitted a field and CsvRecord.IsNull(ordinal) to inspect a present field's null state. Without a schema, this identifies CsvReaderOptions.NullValue; schema converters and defaults follow the canonical reader's IsDBNull result. An omitted field is not also reported as null. The path falls back to correct sequential record access when selected CSV options or a record shape cannot use the span-batch parser. Parallel execution uses more working memory and thread-pool work; small or cheap rows may be faster through the ordinary sequential API.

Use AggregateTextRowsAsParallel when the result is a total or another reduced state. It updates an accumulator directly from each borrowed CsvRecord, then merges completed partition states in source order. It does not create a projected result or array entry for every row:

Totals totals = CsvDocument.AggregateTextRowsAsParallel(
    csvText,
    static () => new Totals(),
    header => {
        int units = header.GetOrdinal("Units");
        return (ref Totals state, CsvRecord row) => {
            state.Rows++;
            state.Units += row.GetInt64(units);
        };
    },
    static (left, right) => new Totals {
        Rows = left.Rows + right.Rows,
        Units = left.Units + right.Units
    },
    parallelOptions: new ParallelRowMappingOptions {
        MaxDegreeOfParallelism = 8
    },
    cancellationToken: cancellationToken);

public struct Totals {
    public long Rows;
    public long Units;
}

The factory creates a neutral state for the result and independent states for each partition. It can run concurrently, as can the record callback. Merge runs on the calling thread in source-partition order and must be associative because partition grouping can change with the worker and batch settings. Accumulator memory and resources belong to the caller; user states are never disposed by the reader. Keep borrowed records and spans inside the callback. Schema conversion and unsupported parsing settings retain the canonical sequential reader behavior. This API accepts decoded text; it does not load a file. All started workers finish before the operation returns or throws.

Check CsvRecord.IsNull and IsMissing before non-nullable typed access. For example, without a schema, NullValue = "-1" marks that source text as null: GetSpan and GetString still expose "-1", while GetInt32 rejects the null field with InvalidCastException. Configured schema converters and defaults retain the canonical reader behavior. Original callback and factory failures propagate after the started workers finish; internal worker cancellation does not replace the original exception.

AggregateRowsAsParallelAsync applies the same accumulator delegates to a file or stream with incremental asynchronous I/O on .NET 8 and later:

Totals totals = await CsvDocument.AggregateRowsAsParallelAsync(
    "large.csv",
    static () => new Totals(),
    header => {
        int units = header.GetOrdinal("Units");
        return (ref Totals state, CsvRecord row) => {
            state.Rows++;
            state.Units += row.GetInt64(units);
        };
    },
    static (left, right) => new Totals {
        Rows = left.Rows + right.Rows,
        Units = left.Units + right.Units
    },
    parallelOptions: new ParallelRowMappingOptions {
        MaxDegreeOfParallelism = 8,
        BatchSize = 256
    },
    cancellationToken: cancellationToken);

For eligible unquoted records, span callbacks avoid materializing field strings. Pooled batches own the decoded text and null/missing metadata while the source advances. Quoted records, interning, quote normalization and field-length checks use the canonical parser. The queue holds at most the configured degree of batches, with no mapped result per row. Explicit and inferred schema conversion uses asynchronous sequential consumption. The file overload closes its reader on success and failure. The stream overload starts at the current position and leaves the stream open. Callbacks have no thread affinity; completed states merge sequentially in source order, and all workers finish before return or failure.

When BatchSize is omitted, asynchronous parallel aggregation uses up to 1,024 records per worker batch. The copied text allowance scales with the effective batch capacity, up to 262,144 characters per batch; larger records use the canonical string fallback. Larger batches reduce scheduling overhead but can buffer more input before the first callback. Set BatchSize = 256, as in the example, when smaller batches suit the workload. The queue remains bounded by MaxDegreeOfParallelism.

On .NET 8 and later, explicit DateOnly and TimeOnly targets are supported by RowsAs<T>, GetFieldValue<T>, and CsvColumnBuilder.AsDateOnly() / AsTimeOnly(). Default schema inference remains DateTime, so moving between target frameworks does not silently change a column's inferred type.

Set CsvLoadOptions.MappingErrorValuePolicy (or CsvReaderOptions.MappingErrorValuePolicy for a reader) to DataMappingErrorValuePolicy.Redact when schema and row-mapping failures must not include source values or custom-converter exception details. The default is Include for compatibility.

Read once or edit

Use CsvDocument.OpenReader when the caller only needs a forward-only ADO.NET reader. CSV parsing, delimiter handling, schema inference, limits, and stream ownership remain in OfficeIMO.CSV.

using OfficeIMO.CSV;

using var reader = CsvDocument.OpenReader("large.csv");
while (reader.Read()) {
    int id = reader.GetInt32(reader.GetOrdinal("Id"));
    string status = reader.GetString(reader.GetOrdinal("Status"));
    Console.WriteLine($"{id}: {status}");
}

Use CsvDocument when the file must be transformed or saved again. Operations such as SortBy, Filter, and AddColumn require materialized rows:

var transformed = CsvDocument.Load("large.csv")
    .AddColumn("ImportedUtc", _ => DateTime.UtcNow)
    .Filter(row => row.AsString("Status") == "Ready")
    .SortBy(row => row.AsInt32("Id"));

transformed.Save("ready.csv");

CsvDocument.OpenReader returns a CsvDataReader derived from ADO.NET's DbDataReader, so it also plugs directly into DataTable.Load and provider bulk-copy APIs. Enable inference when delimited text should expose typed columns:

using System.Data;
using System.Globalization;
using OfficeIMO.CSV;

using CsvDataReader reader = CsvDocument.OpenReader("large.csv", new CsvReaderOptions {
    Culture = CultureInfo.InvariantCulture,
    InferSchema = true,
    SchemaSampleRows = 1000
});

var table = new DataTable();
table.Load(reader);

For imports with expensive typed conversions, benchmark bounded parallel projection on the reader before enabling it. Input size alone does not make worker scheduling worthwhile. Parsing remains single-owner, completed batches are returned in source order, and the caller still consumes one DbDataReader, so the same reader can be passed to SqlBulkCopy or another provider bulk-copy API:

var schema = new CsvSchemaBuilder()
    .Column("Id").AsInt32()
    .Column("Amount").AsType(typeof(decimal))
    .Column("CreatedUtc").AsDateTime()
    .Done()
    .Build();

using CsvDataReader reader = CsvDocument.OpenReader("large.csv", new CsvReaderOptions {
    Schema = schema,
    ParallelProcessing = new CsvDataReaderParallelOptions {
        MaxDegreeOfParallelism = 4,
        BatchSize = 4096
    }
});

Parallel processing is opt-in and targets typed value conversion. String-only readers keep their lower-overhead sequential fast path. The defaults use at most four workers and bounded batches; tune either setting only with a representative workload because more workers can be slower on multi-domain or hybrid CPUs. Custom schema converters may run concurrently in this mode and must be thread-safe; keep the reader sequential when a converter depends on mutable single-threaded state.

OpenReader is the streaming forward-only entry point. On .NET 8 and later, OpenReaderAsync performs incremental asynchronous source I/O with explicit delimiters or bounded detection, and optional ordered parallel typed projection. Use CsvDocument.Load when an editable materialized document is required. LoadAsync materializes the document. SaveAsync formats and writes one record at a time through asynchronous destination I/O, without buffering the complete serialized file. Its temporary memory follows the largest record. Path replacements stage output before committing it; appends write directly and can leave a partial append on failure. Successful stream saves replace a seekable stream's contents and rewind it to the beginning. Non-seekable streams receive output at their current position. Caller-owned streams stay open and can contain partial output after cancellation, formatting failure, or destination I/O failure.

Streaming readers also implement ICsvDataReaderPositionMetadata. Its RecordNumber is the one-based data-record number, while PhysicalLineNumber and PhysicalEndLineNumber identify the source lines for the current record when the selected reader path retains that information. Physical line values are null for materialized paths rather than estimated.

CSV data readers clear the current row and its position when Read, ReadAsync or HasRows lookahead throws, and reject subsequent advances, including parallel mapping. Scalar getter conversion errors leave the current row available.

Real-world headers

CSV exports often contain blank or repeated header names. By default, blank headers are generated as H1, H2, and duplicate names are renamed with suffixes so name-based row access stays unambiguous:

var document = CsvDocument.Parse("Name,Name\nAlpha,Beta\n");

Console.WriteLine(string.Join(", ", document.Header));
// Name, Name_2

Use DuplicateHeaderBehavior when a pipeline needs to preserve source names exactly or reject ambiguous files:

var strict = new CsvLoadOptions {
    DuplicateHeaderBehavior = CsvDuplicateHeaderBehavior.Throw
};

CsvDocument.Load("input.csv", strict);

Append static metadata columns during import when a database or audit pipeline needs source context on every row:

var document = CsvDocument.Load("input.csv", new CsvLoadOptions {
    StaticColumns = new Dictionary<string, object?> {
        ["SourceFile"] = "input.csv",
        ["ImportedUtc"] = DateTime.UtcNow
    }
});

Use NullValue and DateTimeFormats when a CSV producer uses explicit null tokens or non-default date shapes:

var document = CsvDocument.Load("input.csv", new CsvLoadOptions {
    NullValue = "<null>",
    DateTimeFormats = new[] { "dd-MMM-yyyy", "yyyyMMdd-HHmmss" }
});

DateTime created = document.AsEnumerable().First().AsDateTime("Created");

The parser defaults to lenient quoted-field handling for compatibility with common PowerShell CSV imports. Use strict mode when malformed quotes should fail the import:

var document = CsvDocument.Load("input.csv", new CsvLoadOptions {
    QuoteParsingMode = CsvQuoteParsingMode.Strict
});

Use DelimiterText for multi-character delimiters such as || or ::. Quoted fields can still contain the delimiter text:

var document = CsvDocument.Parse(
    "Name||Value\nAlpha||\"one||two\"\n",
    new CsvLoadOptions { DelimiterText = "||" });

document.Save("pipes.csv", new CsvSaveOptions {
    DelimiterText = "||",
    NewLine = "\n"
});

Long-running import paths can opt into cancellation and progress reporting without changing the document model:

using var cancellation = new CancellationTokenSource();

using var reader = CsvDocument.OpenReader("large.csv", new CsvReaderOptions {
    CancellationToken = cancellation.Token,
    ProgressReportInterval = 10_000,
    ProgressCallback = progress =>
        Console.WriteLine($"{progress.RecordsRead} records read")
});

long rowsRead = 0;
while (reader.Read()) {
    rowsRead++;
}

Console.WriteLine($"Imported {rowsRead} rows");

Export options

CSV output supports null tokens, date/time formatting, UTC conversion, append, no-clobber checks, compression, quoting, encoding, and formula escaping. Formula escaping applies to text and configured text tokens; typed negative numeric values remain numeric:

CsvDocument.Load("input.csv")
    .Save("output.csv.gz", new CsvSaveOptions {
        NullValue = "<null>",
        DateTimeFormat = "yyyy-MM-ddTHH:mm:ssZ",
        UseUtc = true,
        CompressionType = CsvCompressionType.Auto,
        FormulaInjectionPolicy = CsvFormulaInjectionPolicy.Escape,
        NewLine = "\n"
    });

Append without rewriting the header:

CsvDocument.Load("next.csv")
    .Save("combined.csv", new CsvSaveOptions {
        Append = true,
        IncludeHeader = false
    });

Append inserts a record separator when the existing file has no terminal newline. Empty appends leave the file unchanged. Use the existing file's encoding and dialect. Documents retain the full loaded DelimiterText, including multi-character delimiters, for default saves. ICsvDataReaderDialectMetadata.DelimiterText exposes that dialect through data readers; Delimiter remains the first character for existing consumers.

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");

Use direct object writing for larger exports when the caller does not need to materialize a CsvDocument first. The same save options are honored, including null tokens, date/time formatting, UTC conversion, compression, append, and no-clobber checks:

CsvDocument.SaveObjects("summary.csv.gz", rows, new CsvSaveOptions {
    NullValue = "<null>",
    DateTimeFormat = "yyyy-MM-ddTHH:mm:ssZ",
    UseUtc = true,
    CompressionType = CsvCompressionType.Auto
});

When the source is already an IDataReader, write it directly to a path or stream without introducing a second serialization path:

using OfficeIMO.CSV;

using var reader = command.ExecuteReader();
CsvDocument.WriteDataReader("summary.csv.gz", reader, new CsvSaveOptions {
    CompressionType = CsvCompressionType.Auto
});

For large database exports with CPU-heavy quoting or value formatting, opt in to ordered parallel formatting. The source reader is still consumed by one thread; detached row batches are formatted concurrently and committed in the original order:

using var reader = command.ExecuteReader();
CsvDocument.WriteDataReaderParallel(
    "summary.csv.gz",
    reader,
    new CsvSaveOptions { CompressionType = CsvCompressionType.Auto },
    new CsvWriteParallelOptions {
        MaxDegreeOfParallelism = 4,
        BatchSize = 4096,
        MaximumBufferedCellsPerBatch = 1_048_576
    },
    cancellationToken);

The parallel writer keeps at most two batches in memory. Its effective row count per batch is the smaller of BatchSize and MaximumBufferedCellsPerBatch / reader.FieldCount. On the multi-worker path, every request whose schema is wider than the cell budget is rejected before field-type inspection, snapshot planning, or output mutation. Readers within that width whose values require provider-owned access continue through the sequential fallback and do not allocate parallel batches. An explicit or environment-derived single-worker configuration delegates directly to WriteDataReader, so the parallel batch-width limit does not apply. Raise the cell budget only for a trusted schema whose working set the application can afford; otherwise select fewer fields or use sequential WriteDataReader. Custom values and format providers used during parallel formatting must support concurrent read-only access. For small or simply formatted exports, WriteDataReader avoids the thread-pool and batch-buffering overhead and may be faster; measure the real row shape on the target machine before choosing the parallel path.

When the caller already has projected arrays, pass the shared schema once. The writer validates every row width without repeating column-name validation:

object?[][] projectedRows = {
    new object?[] { "Alpha", 10, true },
    new object?[] { "Beta", 20, false }
};

using var output = File.CreateText("summary.csv");
using var csv = new CsvRowWriter(output);
csv.WriteRows(new[] { "Name", "Count", "Active" }, projectedRows);

Use WriteTextRows for arrays that are already culture-formatted; CSV escaping and row-width validation still apply.

Use CsvRowWriter.CreateStream to write at a stream's current position. Its leaveOpen argument controls the supplied stream's lifetime; disposal completes any compression wrapper. CompressionType.Auto means no compression for a stream. CreateFile applies file encoding, compression, append, and no-clobber options.

On .NET 8 and later, WriteUtf8Row accepts already-formatted UTF-8 fields:

using OfficeIMO.CSV;
using System.Text;

using var output = new MemoryStream();
using (var csv = CsvRowWriter.CreateStream(output, leaveOpen: true)) {
    ReadOnlyMemory<byte>?[] row = {
        Encoding.UTF8.GetBytes("Zażółć 🚀"),
        ReadOnlyMemory<byte>.Empty,
        null
    };
    csv.WriteUtf8Row(new[] { "Name", "EmptyText", "Missing" }, row);
}
byte[] encodedCsv = output.ToArray();

The writer consumes borrowed field memory before returning and validates every field before writing that row or its initial header. Invalid UTF-8 throws DecoderFallbackException. Null uses CsvSaveOptions.NullValue; empty memory is an empty text field. Quoting, formula escaping, delimiters, and newlines follow the ordinary text-row options. UTF-8 stream and file output without a BOM copies field bytes directly. A supplied TextWriter, another destination encoding, BOM output, or file append uses the text encoding path.

After establishing the columns, use WriteUtf8Row(values) or the accessor overload WriteUtf8Row(valueCount, state, valueAccessor) for later rows. The accessor is called once per field and its returned memory is consumed before the method returns. Keep all returned field memory valid for the entire call.

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
});

Current limits and related packages

• OfficeIMO.CSV provides CSV parsing, writing, transforms, and validation.
• DelimiterText supports explicit multi-character delimiters. Delimiter auto-detection is still character-candidate based.
• Database bulk copy and provider behavior are available through DbaClientX or the consuming data-access layer rather than this package.
• Use OfficeIMO.Reader.Csv for unified Reader integration.
• Use OfficeIMO.Excel for workbook behavior.

Targets and license

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

Dependency footprint

• External: No third-party CSV engine. System.Buffers and .NET Framework reference assemblies support compatibility targets.
• OfficeIMO: OfficeIMO.Core. Parsing, streaming, schemas, transforms, compression, and object mapping are first-party.

See the complete OfficeIMO package map for related formats and conversion paths.

Generated capability summary

This table is generated from the package-neutral OfficeIMO operation catalog. The detailed source contracts remain authoritative for feature-level behavior and limitations.

The complete rows for OfficeIMO.CSV are published in the generated operation contract.