Csv Haibara

RFC 4180 Low memory usage Support nested objects Support class and struct No dependencies Ultra-rapid

Latest version: 1.0.16


A lightweight and versatile library for reading and writing CSV files. Focus on smooth asynchronous processing, streaming large files efficiently, and maintaining consistent rules for serialization and deserialization.

Install

Package Manage Console

Install-Package CsvHaibara

.NET CLI

dotnet add package CsvHaibara
Download at Nuget
GitHub Demo project

Class StreamIn (used in reading file)

StreamIn streamIn = new(ICsvHaibara csvHaibara, string path);
StreamIn streamIn = new(ICsvHaibara csvHaibara, Stream stream);

Class StreamOut (used in writing file)

StreamOut streamOut = new(ICsvHaibara csvHaibara, string path);
StreamOut streamOut = new(ICsvHaibara csvHaibara, Stream stream);

Serialize

class Person
{
    public string Name { get; set; }
    public bool Gender { get; set; }
    public int Age { get; set; }
}
                            
using CsvHaibaraNt.Core;

string path = "person.csv";
var persons = new List<Person>
{
    new Person { Name = "Alice", Gender = false, Age = 20 },
    new Person { Name = "Adam", Gender = true, Age = 25 }
};

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    using (StreamOut streamOut = new(csvHaibara, path))
        await csvHaibara.SerializeAsync<Person>(streamOut, persons, true);
}

Deserialize to generic objects (class or struct)

class Person
{
    public string Name { get; set; }
    public bool Gender { get; set; }
    public int Age { get; set; }
}
                            
using CsvHaibaraNt.Core;

string path = "person.csv";
var lst = new List<Person>();

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    using (StreamIn streamIn = new(csvHaibara, path))
    {
        await foreach (Person person in csvHaibara.DeserializeAsync<Person>(streamIn, true))
            lst.Add(item);
    }
}

Deserialize to dynamic objects

using CsvHaibaraNt.Core;

string path = "person.csv";
var lst = new List<dynamic>();

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    using (StreamIn streamIn = new(csvHaibara, path))
    {
        await foreach (var obj in csvHaibara.DeserializeAsync(streamIn, true))
            lst.Add(obj);
    }
}

Deserialize to anonymous objects

using CsvHaibaraNt.Core;

string path = "person.csv";
var lst = new List<dynamic>();
var objDefinition = new 
{
    Name = string.Empty;,
    Gender = default(bool)
    Age = default(int)
};

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    using (StreamIn streamIn = new(csvHaibara, path))
    {
        await foreach (var obj in csvHaibara.DeserializeAsync(objDefinition, streamIn, true))
            lst.Add(obj);
    }
}

Ignore columns

All ignored properties will be left as their default value, e.g. 0 for int, false for bool

When writing file, all ignored columns disappear in output file

When reading file, all ignored columns MUST NOT APPEAR in input file

class Person
{
    public string Name { get; set; }
    public bool Gender { get; set; }
    public int Age { get; set; }
}
                            
using CsvHaibaraNt.Core;

string path = "person.csv";
var lst = new List<Person>();

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    csvHaibara.Ignore<Person>(m => m.Gender, m => m.Age);
    using (StreamIn streamIn = new(csvHaibara, path))
    {
        await foreach (Person person in csvHaibara.DeserializeAsync<Person>(streamIn, true))
            lst.Add(item);
    }
}

Include all columns

Later on, when you want to take all ignored columns again

using CsvHaibaraNt.Core;

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    csvHaibara.IncludeAll<Person>();
}

Setting Delimiter

Default Delimiter is comma

using CsvHaibaraNt.Core;

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    csvHaibara.Delimiter = ';';
}

Setting Encoding

Default Encoding is UTF8

using CsvHaibaraNt.Core;

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    csvHaibara.Encoding = Encoding.ASCII;
}

Setting Escape

Default Escape is "

using CsvHaibaraNt.Core;

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    csvHaibara.Escape = '^';
}

Setting CultureInfo

Default CultureInfo is CurrentCulture

using CsvHaibaraNt.Core;

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    csvHaibara.CultureInfo = CultureInfo.InvariantCulture;
}

Setting NullStringValue

To distinguish null string from empty string.

By default, missing value of string field is treated at an empty string.

Therefore, in order to get null value, you have to indicate a special string as null value. If any string field gets this value, it is considered as null value. Make sure this is the unique string to avoid unexpected results.

Default NullStringValue is null.

using CsvHaibaraNt.Core;

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    csvHaibara.NullStringValue = "None";
}

Boolean Converter

Instead of traditional values true/false. You want to use other values like yes/no, 1/0

public class Person
{
    public string Name { get; set; }

    [BooleanFalseValue("0")]
    [BooleanTrueValue("1")]
    public bool Gender { get; set; }

    public int Age { get; set; }
}

Setting column header

Custom column header will be display in output file

public class Person
{
    [ColumnHeader("Given Name")]
    public string FirstName { get; set; }

    [ColumnHeader("Family Name")]
    public string LastName { get; set; }
}

DateTime Format Printout

Declare the exact format DateTime value that you want to print out.

This attribute is only useful in writing file and for DateTime type.

public class Person
{
    public string Name { get; set; }

    [DateTimeFormat("yyyy-MM-dd")]
    public DateTime EntryDate { get; set; }
}

Assign object as default value if all fields are null or missing values

Once this method is called with parameter true, then when reading file, if all fields are null or missing values, that object will be assigned as null class object or default value struct object or its default value if any

The default treatment is corresponding with parameter false, that object is still not null

public class Person
{
    public string Name {  get; set; }
    public Address Address1 { get; set; }
    public int Age {  get; set; }
    public Address Address2 { get; set; }
}

public class Address
{
    public string City { get; set; }
    public string Country { get; set; }
}
                            
using CsvHaibaraNt.Core;

using (ICsvHaibara csvHaibara = CsvHaibaraConfiguration.GetCsvHaibara())
{
    csvHaibara.SetDefaultIfAllFieldsNullOrMissing<Address<(true);
}

Note: default value in different cases

public class Person
{
    public string FirstName { get; set; }               //default value is null
    public string LastName { get; set; } = "name";      //default value is "name"
    public Address Address1 { get; set; }               //default value is null (Address is a class)
    public int Age {  get; set; }                       //default value is 0
    public Address Address2 { get; set; } = new();      //default value is new Address()
    public int Points { get; set; } = 100;              //default value is 100
}

Exception

Exeption only occurs in these cases:

- Open input/output file failed

- There is conflict between Delimiter and Escape
    Ex: Delimiter and Escape are both comma

- There is conflict between Delimiter and CultureInfo's decimal point
    Ex: Delimiter and decimal point are both comma

- There is conflict between Escape and CultureInfo's decimal point
    Ex: Escape and decimal point are both comma

- When writing file, list of objects is null

- Cast value failed
    Ex:
    public class Person
    {
        public string Name { get; set; }
        public bool Gender { get; set; }
        public int Age { get; set; }
    }

    Input file:
    Mary, false, c

    Then it should be failed when parsing column Age

FAQs

Q: Does CsvHaibara support deserializing to generic objects of both class and struct? Or only supporting class? A: Since version 1.0.14, CsvHaibara supports both class and struct. 
Q: How does CsvHaibara handle case when there are some missing fields in input file?
A: If any missing field occurs, the corresponding property will be set as its default value.

Ex:
public int Count_1 { get; set; }            //Count_1's default value is 0
public int Count_2 { get; set; } = 100;     //Count_2's default value is 100
                            
Q: How does CsvHaibara print null object?
A: All its properties will be considered as missing values.
   - For string type, it will be printed as null. If you already set another value   
   representing for NullStringValue, then that value will be used.
   - For other types, they will be printed as missing value.

Copyright © Vuong Nguyen  -  2026