Click here to Skip to main content
15,917,968 members
Articles / Web Development / HTML

FileHelpers v3.1 - Delimited (CSV) or Fixed Data Import/Export Framework

Rate me:
Please Sign up or sign in to vote.
4.84/5 (447 votes)
17 Aug 2015MIT8 min read 2.8M   2.8K   973   364
An easy to use .NET library to read/write strong typed data from files with fixed length or delimited records (CSV). Also has support to import/export data from different data storages (Excel, Acces, SqlServer, MySql)

FileHelpers Home Page

FileHelpers v 3.1

Image 1


The FileHelpers are an easy to use library to import/export data from fixed length or delimited flat files (like the CSV). FileHelpers also has support to import/export data from different data storages (Excel, Acces, SqlServer).

The library has a set of converters for the basic types and can be easily extended to provide custom converters.

The main idea is pretty simple:

You can strong type your flat file (fixed or delimited) simply describing a class that maps to each record of the file and work with your file like a strong typed .NET array.

Image 2

Basic Uses

Directly between the files and the .NET source code:

general read write of filehelpers 

It also can be used as an intermediate between files and MS Access or MS SqlServer tables:


General read write to data storage

Download Instructions

The recommend method to install the library is use the NuGet Package

Via de NuGet Console:     Install-Package FileHelpers

Or you can use the Visual Studio NuGet Explorer to search for FileHelpers

add references


Quick Start Guide (easy Image 6Image 7Image 8Image 9 steps)

Image 10

To start using the FileHelpers Library you only need to add a reference in your project to the file: FileHelpers.dll. You can find it in the Release directory of the distribution. Tip: remember to leave the FileHelpers.xml file to get Intellisense support.

Image 11

Image 12

Next you need to define a class that maps to the record in the source/detination file. For this example we use a file with this format delimited by a |:


The class that we refer can be like this:

public class Orders
   public int OrderID;

   public string CustomerID;

   [FieldConverter(ConverterKind.Date, "ddMMyyyy")]
   public DateTime OrderDate;

   public decimal Freight;

Image 13

Later you must instantiate a FileHelperEngine and Read/Write files:

var engine = new FileHelperEngine<Orders>();

/// to Read use:
var res = engine.ReadFile("input.txt");

/// to Write use:
engine.WriteFile("output.txt", res);

Image 14

Finally you can use the res array to access each item in the file, for example:

foreach (Orders order in res)
   Console.WriteLine("Order Info:");
   Console.WriteLine(order.CustomerID + " - " +

Working with FixedLength files is exactly the same but you need to use the [FixedLengthRecord] and [FieldFixedLength] attributes.

More Examples

We have ton of examples in our web site to learn to use the library from every angle

Image 15

Who needs the File Helpers Library?

In almost every project there is a need to read/write data from/to a flat file of a specified format. Writing the code to process these files is not hard, you can use String.Split or String.SubString, but if you do that the code sometimes becomes hard to read and change. If you want to add support later for quoted string, multiline, convert types, etc. these things tend to get complicated.

So with the FileHelpers you don't need to worry about changes in the file structure because you can change the Type, Converters, Triming, Length in seconds.

Another place where you can find the FileHelpers useful is for log parsing, data warehouse and OLAP applications, communication between systems, file format transformations (for example from a fixed length to an CSV file), load test data into your NUnit tests and a lot more!!!

This library aims to provide an easy and reliable way to accomplish all these tasks.

Roslyn Analyzer

Our Roslyn Analyzer helps you to use the library in the right way.

Image 16

The current Analyzer implements:

  • Recomends to use the generic version when you use an engine with a typeof() in the constructor
  • Suggest to use [FieldHidden] instead of [FieldIgnored] or [FieldNotInFile]
  • Use FileHelpers.Dynamic instead of FileHelpers.RunTime namespace
  • Use IComparable instead of the obsolete IComparableRecord 

next version will implement

  • Check that record class contains valid record attributes
  • Check that record class contains any field
  • Check other obsolete methods
  • Convert engine.ReadFile in async version with foreach

You can join the development of the analyzer, join us in the Gitter chat:



Record Class Wizard

Since version 1.3.5 the library has had a Record Class Wizard to generate the record class. The Record Class Wizard allows you to generate your record mapping class, save the definition, generate code based on snippets (Read File, Read with Generics, ReadAsync and so on).

Image 17
Click to see how it works

Main Features


 Easy to use

The FileHelpers library is straightforward to learn and use.
Check the Examples

 Auto Converters

The library has a set of converters for common types and can be easy extended to provide custom converters.
Check the Example

 Event Support

The engines of the library contain events to make it easier to extend the behavior of the library
Check the INotifyRead andINotifyWrite Examples

 High Performance

The library doesn't use reflection to get or set the field values, it uses dynamic code generation

 Wide framework support

You can use the library in
.NET and Mono!!

 Multiple Error Modes

You can configure the library to use different ErrorModes.
Check the example


You can use the library to sort files with millon of records and MBs
Check the Example

 File Transform Engine

To convert files in one format to another (for example a file with CSV to a fixed length record format)
Check the Example


Provides the ability to compare files with the same record layout
Check the Example


You can process hierarchical data with this engine
Check the Example

 Nullable Types

The library supports Nullable types in the core
Check the Example

 Record by Record Mode

You can use the library to read line by line and not the whole file.
Check the Example

 Open Source

The library is completely free to use in any kind of development

 Format Autodetection

The library has an smart feature that based in some sample files can deduce the Record Class
Check the Example


We provide a Wizard app to help in the creation of the Record Class
Check the Online Wizard


Progress Notification

Here is a screenshot of the progress notification of the demo app.

Since versión 1.4.0 you can get notified of the progress of each operation of the library to show feedback to the user or whatever you want.

Image 18

Class Diagram

Image 19

Detailed Diagram

Detailed Diagram


The library contains more than 650 NUnit tests to ensure correctness:

Sample image

List of Converters Arguments

Here is a list of the parameters that you can give to the default converters:


Arg1: A string with the DateTime format that the engine passes to the DateTime.Parse function.

Arg2: A string with the encoding used for string convertions


// By default the engines use: "ddMMyyyy"
public DateTime ShippedDate;

// Parse these dates:  1-1-2006   01-1-2006   30-01-2006
[FieldConverter(ConverterKind.Date, "d-M-yyyy" )]
public DateTime ShippedDate;

// Parse these dates:  1-1-2006   01-1-2006   01-30-2006
[FieldConverter(ConverterKind.Date, "M-d-yyyy" )]
public DateTime ShippedDate;

// Parse these dates:  01/3/2006   30/02/2006
[FieldConverter(ConverterKind.Date, "d/M/yyyy" )]
public DateTime ShippedDate;

// Parse these dates:  01042006   30022006
[FieldConverter(ConverterKind.Date, "ddMMyyyy" )]
public DateTime ShippedDate;

// Parse these dates:  04/January/2006   02/July/2006
[FieldConverter(ConverterKind.Date, "dd/MMMM/yyyy", "en" )] // or "en-US"
public DateTime ShippedDate;

// Parse these dates:  04/Enero/2006   02/Julio/2006
[FieldConverter(ConverterKind.Date, "dd/MMMM/yyyy", "es" )]
public DateTime ShippedDate;

You can check all the supported format strings check the MSDN docs for DateTime.ParseExact 
and here all support cultures

ConverterKind.Double, ConverterKind.Single and ConverterKind.Decimal

Arg1: A string with the character to be used as DecimalSeparator. Valid Values: "." or ",". By default: "."


// "." is the decimal separator by default
public double Freight;

// "." is the decimal separator. (good for autodocumented code)
[FieldConverter(ConverterKind.Double, ".")]
public double Freight;

// "," is the decimal separator.
[FieldConverter(ConverterKind.Double, ",")]
public double Freight;

// The same for the other converters:
// ConverterKind.Decimal and ConverterKind.Single

Integer Converters

ConverterKind.Int16, ConverterKind.Int32, ConverterKind.Int64, ConverterKind.Byte, 
ConverterKind.UInt16, ConverterKind.UInt32, ConverterKind.UInt64, and ConverterKind.SByte

Arg1: A string with the character to be used as DecimalSeparator. Valid Values: "." or ",". By default: "."

WARNING: The library requires a decimal separator here and internally creates the group separator with the counterpart (for example if you provide "." it uses ",")


// "." is the decimal separator by default
// allows you to parse:  12,125 or 1,458,385
public Int32 Amount;

// using "," as decimal separator
// allows you to parse:  12.125 or 1.458.385
[FieldConverter(ConverterKind.Int32, ",")]
public Int32 Amount;

// The same works for the rest of the converts


Arg1: A string that represents the True value 
Arg2: A string that represents the False value

By default, this converter takes the strings "True" (case insensitive) and "1" as true. The values "True" and "False" are returned when converting the field to string.


// By default it reads as true the strings "True" (Case insensitive) and "1"
public bool Shipped;

// Takes as true the string "verdad" and as false the string "mentira" (case insensitive)
[FieldConverter(ConverterKind.Boolean, "Verdad", "MenTiRa")]
public bool Shipped;

// Takes as true the string "1" and as false the string "0"
// You need these params if you want to write, because it use "True" and "False"
[FieldConverter(ConverterKind.Boolean, "1", "0")]
public bool Shipped;

// Takes as true the string "X" and as false the string "-"
[FieldConverter(ConverterKind.Boolean, "X", "-")]
public bool Shipped;


Version 3.1, July 2015

Hi everyone again !!

The FileHelpers has reached a big Milestone today we are releasing the 3.1 version!

Now with full support for .NET 4.0, 4.5 and Mono and with a ton of news and enhancements.

After some time off for different reasons we are now trying to update the library in a more regular fashion. We redesigned the HomeSite with a Material Design Template from GeeksLabs

Main changes

  • Docs rewritten thanks to the work of Ken Foskey and Matthias Cavigelli
  • NEW: Full .NET 2.0, 4.0 & 4.5 support.
  • NEW: Added support for MONO !!
  • NEW: FieldOrder: a new attribute to override the default order of fields.
  • NEW: Partial support to use Autoproperties
  • NEW: Async Methods returns IDisposable to allow using() statements that autoclose files on ends or exception.
  • NEW: Events for the Async engines.
  • NEW: The events args now have TotalBytes and CurrentBytes to allow you show progress while reading or writing.
  • NEW: FieldIndexers you can now get the values in the AsyncEngine like in the DataReader of ADO.NET =) You can access them via index or fieldName (at the moment case sensitive). This also completes the RunTime records support
  • NEW: SmartFormatDetector: A class designed to discover the format of delimited and flat files based on sample files. It is integrated with the wizzard
  • NEW: Better Delimited validations to make sure that the file contains the right number of fields
  • NEW: FieldValueDiscarted: a new attribute to allow the value of a particular field to be read but not stored in the record class (this was a very requested feature)
  • NEW: BigFileSorter: if you need to sort big files, you can use this feature that implements External Sorting
  • MOD: The error messages have been made more meaningful. In all exceptions you get: FieldName, ColumnNumber, LineNumber etc.
  • NEW: FieldNotEmpty: Indicates whether the target field needs to be populated with a non-empty value.

Breaking Changes

  • Removed support for .NET Compact Framework
  • [FieldIgnored] => [FieldHidden]
  • IComparableRecord<T> => IComparable<T>

Minor Changes

  • Better caching of internal classes
  • The core code of the library was refactored to make easier to extend it.
  • Better performance.
  • ADD: UpdateLinks properties, allow to specify how the library must handle Workbook links (thanks to Stefan Schälle)
  • A ton of new examples, autogenerated from FileHelpers.Examples project
  • FIX: A little problem with the quoted fields in the wizard
  • More documentation has been added to the Library source code. It is now even easier to get involved in development!

Licence (MIT)

FileHelpers Library is @Copyright 2005-2015 to Marcos Meli but it's source code and the binaries are free for commercial and non commercial use.

Vote for this article if you like the library.


This article, along with any associated source code and files, is licensed under The MIT License

Written By
Architect Devoo
Argentina Argentina
Marcos Meli v1.0 was released at august of 1980 by Francisco and Mabel Inc.
He´s from Bahia Blanca, Argentina.

He enjoy developing from the 12 years, has a degree in Computer Science, and of course, love this site and .NET in general.

He is the lead developer of the FileHelpers Library.

Marcos is also the co-funder of Devoo.Net.
A company that provides Object Oriented Components & Libraries for .NET developers (mostly open source)

Comments and Discussions

GeneralReading MS CSV files Pin
udikantz8-Aug-07 17:33
udikantz8-Aug-07 17:33 
GeneralRe: Reading MS CSV files Pin
Marcos Meli9-Aug-07 3:34
Marcos Meli9-Aug-07 3:34 
GeneralRe: Reading MS CSV files Pin
udikantz9-Aug-07 8:37
udikantz9-Aug-07 8:37 
GeneralRe: Reading MS CSV files Pin
Marcos Meli9-Aug-07 11:09
Marcos Meli9-Aug-07 11:09 
GeneralRe: Reading MS CSV files Pin
Marcos Meli17-Aug-07 3:30
Marcos Meli17-Aug-07 3:30 
GeneralRe: Reading MS CSV files Pin
Shumaker21216-Dec-09 21:44
Shumaker21216-Dec-09 21:44 
GeneralWOW!!!! Pin
me@vbman.com9-May-07 20:09
me@vbman.com9-May-07 20:09 
GeneralRe: WOW!!!! Pin
Marcos Meli27-May-07 11:57
Marcos Meli27-May-07 11:57 
Hi there

I dont see the comments sorry for the delay

Im happy that you like the library, if you have any question you can enter our support forums:

PS: Is a very good idea to add a folder watcher, I dont know too much about XML but we are thinking in add a simple mapping, anyway nothing that cant be done out of the box.

Any donation is more than wellcome


GeneralASP.NET and MemoryStream Pin
Kevin Jensen20-Apr-07 17:50
Kevin Jensen20-Apr-07 17:50 
GeneralUrgent, Please help! Escape Characters [modified] Pin
Shahin7720-Apr-07 7:38
Shahin7720-Apr-07 7:38 
Generalnullable data types with runtime records(class builder) Pin
boudinov19-Apr-07 15:52
boudinov19-Apr-07 15:52 
GeneralRe: nullable data types with runtime records(class builder) Pin
Marcos Meli19-Apr-07 16:43
Marcos Meli19-Apr-07 16:43 
GeneralRe: nullable data types with runtime records(class builder) Pin
boudinov20-Apr-07 6:19
boudinov20-Apr-07 6:19 
GeneralWonderful Piece of Software Pin
JasonGarco14-Apr-07 18:17
JasonGarco14-Apr-07 18:17 
GeneralRe: Wonderful Piece of Software Pin
Marcos Meli19-Apr-07 16:46
Marcos Meli19-Apr-07 16:46 
GeneralRe: Wonderful Piece of Software Pin
joseguia13-Jul-07 4:12
joseguia13-Jul-07 4:12 
GeneralAwesome Pin
Jericho11-Apr-07 7:40
Jericho11-Apr-07 7:40 
GeneralRe: Awesome Pin
Marcos Meli11-Apr-07 7:53
Marcos Meli11-Apr-07 7:53 
QuestionMySQL? Pin
UnRusoDeCaracas10-Apr-07 6:53
UnRusoDeCaracas10-Apr-07 6:53 
AnswerRe: MySQL? Pin
Marcos Meli10-Apr-07 18:01
Marcos Meli10-Apr-07 18:01 
GeneralRe: MySQL? Pin
UnRusoDeCaracas12-Apr-07 7:27
UnRusoDeCaracas12-Apr-07 7:27 
GeneralExcelent!!! Pin
gonzalor10-Apr-07 4:35
gonzalor10-Apr-07 4:35 
GeneralRe: Excelent!!! Pin
Marcos Meli10-Apr-07 4:45
Marcos Meli10-Apr-07 4:45 
GeneralWooopie! Pin
FabioMaulo31-Mar-07 12:07
FabioMaulo31-Mar-07 12:07 
GeneralRe: Wooopie! Pin
Marcos Meli31-Mar-07 14:37
Marcos Meli31-Mar-07 14:37 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.