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

• Download Latest version - 5.600 Kb (local copy)
• Source in GitHub (local source copy)

FileHelpers Home Page

FileHelpers v 3.1

Introduction Basic Uses Download Info Quick Start Guide More Examples Who Needs the FileHelper Library ? Roslyn Analyzer Class Wizard Main Features History and Last Changes !!

Introduction

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.

Basic Uses

Directly between the files and the .NET source code:

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

Download Instructions

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

www.nuget.org/packages/FileHelpers/

Via de NuGet Console:     Install-Package FileHelpers

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

Quick Start Guide (easy steps)

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.

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 |:

10248|VINET|04071996|32.38
10249|TOMSP|05071996|11.61
10250|HANAR|08071996|65.83
10251|VICTE|08071996|41.34
...............

The class that we refer can be like this:

[DelimitedRecord("|")]
public class Orders
{
   public int OrderID;

   public string CustomerID;

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

   public decimal Freight;
}

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

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 + " - " +
                     order.OrderDate.ToString("dd/MM/yy"));
}

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

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.

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:

https://gitter.im/MarcosMeli/FileHelpers

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).

Click to see how it works

Main Features

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.

Class Diagram

Detailed Diagram

Testing

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

// By default the engines use: "ddMMyyyy"
[FieldConverter(ConverterKind.Date)]
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;

// "." is the decimal separator by default
[FieldConverter(ConverterKind.Double)]
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

// "." is the decimal separator by default
// allows you to parse:  12,125 or 1,458,385
[FieldConverter(ConverterKind.Int32)]
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

// By default it reads as true the strings "True" (Case insensitive) and "1"
[FieldConverter(ConverterKind.Boolean)]
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;

History

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.