DataLink feature is outdated and will be rewritten
The support to interact with other datasources is from the old 1.1 or 2.0 days. We will be rewriting this feature for the next release using lambda expressions, Task and other advanced features of .NET
Excel support is only for basic scenarios
The current implemented Excel support is only for basic scenarios. If you need custom formatting, charts, etc. you must go for a custom
code. It's strongly recommended to directly use the NPOI library
FAQ
My file has headers, how can I ignore it ?
You must use the [IgnoreFirst] attribute. For the footer line you can use the [IgnoreLast] attribute.
I want to write a file with headers
You must use engine.HeaderText = engine.GetFileHeader() before you call WriteFile
Not all the characters from the original file are read
You have a problem with the Encoding. You can pass the encoding to the engines new FileHelperEngine(Encoding.UTF8)
How can I skip certain lines when reading a file
You can capture the BeforeRead event or use the INotifyRead interface
My DateTime field has a different format
Use this attribute with your format:
[FieldConverter(ConverterKind.Date, "M-d-yyyy" )]
Check the Converters page for more info
Performance
Try to use FileHelperAsyncEngine
When reading or writing a large number of records, we recommend using FileHelperAsyncEngine;
it will work faster and use a ton less memory
Use the FieldValueDiscarded attribute for fields that you don't use
If your record class has some fields that are not used, the library will discard the value of fields marked by this attribute
Debugging
Use all the values of the FileHelper Exceptions
We work hard to provide great context info in all exceptions to assist in debugging.
ConvertException
A brief description of the attributes and the usage.
Fixed Length Records
Attribute
Read
Write
FixedLengthRecord Indicates a fixed length record file
X
X
IgnoreFirst
X
IgnoreLast
X
IgnoreEmptyLines
X
ConditionalRecord
X
Delimited Records
Attribute
Read
Write
DelimitedRecord Indicates a delimited record file
X
X
IgnoreFirst
X
IgnoreLast
X
IgnoreEmptyLines
X
ConditionalRecord
X
Fixed Length Fields
Attribute
Read
Write
FieldFixedLength Indicates a length of the field
X
X
FieldConverter
X
X
FieldQuoted
X
X
FieldInNewLine?
X
X
FieldHidden The library will ignore this field
X
X
FieldOptional
X
FieldNullValue
X
FieldTrim ?
X
FieldAlign
X
Delimited Fields
Attribute
Read
Write
FieldDelimiter Indicates a new field end marker
X
X
FieldConverter
X
X
FieldQuoted
X
X
FieldInNewLine?
X
X
FieldHidden The library will ignore this field
X
X
FieldOptional
X
FieldNullValue
X
-
-
Arguments for the Default Converters of the library.
Here is a list of the parameters that you can give to the default converters:
ConverterKind.Date
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
Examples:
// By default the engines use: "ddMMyyyy"[FieldConverter(ConverterKind.Date)]publicDateTimeShippedDate;// Parse these dates: 1-1-2006 01-1-2006 30-01-2006[FieldConverter(ConverterKind.Date,"d-M-yyyy")]publicDateTimeShippedDate;// Parse these dates: 1-1-2006 01-1-2006 01-30-2006[FieldConverter(ConverterKind.Date,"M-d-yyyy")]publicDateTimeShippedDate;// Parse these dates: 01/3/2006 30/02/2006[FieldConverter(ConverterKind.Date,"d/M/yyyy")]publicDateTimeShippedDate;// Parse these dates: 01042006 30022006[FieldConverter(ConverterKind.Date,"ddMMyyyy")]publicDateTimeShippedDate;// Parse these dates: 04/January/2006 02/July/2006[FieldConverter(ConverterKind.Date,"dd/MMMM/yyyy","en")]// or "en-US"publicDateTimeShippedDate;// Parse these dates: 04/Enero/2006 02/Julio/2006[FieldConverter(ConverterKind.Date,"dd/MMMM/yyyy","es")]publicDateTimeShippedDate;
ConverterKind.Double, ConverterKind.Single and ConverterKind.Decimal
Arg1: A string with the character to be used as DecimalSeparator. Valid Values: "." or ",". By default: "."
Examples:
// "." is the decimal separator by default[FieldConverter(ConverterKind.Double)]publicdoubleFreight;// "." is the decimal separator. (good for autodocumented code)[FieldConverter(ConverterKind.Double,".")]publicdoubleFreight;// "," is the decimal separator.[FieldConverter(ConverterKind.Double,",")]publicdoubleFreight;// 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 ",")
Examples:
// "." is the decimal separator by default// allows you to parse: 12,125 or 1,458,385[FieldConverter(ConverterKind.Int32)]publicInt32Amount;// using "," as decimal separator// allows you to parse: 12.125 or 1.458.385[FieldConverter(ConverterKind.Int32,",")]publicInt32Amount;// The same works for the rest of the converts
ConverterKind.Boolean
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.
Examples:
// By default it reads as true the strings "True" (Case insensitive) and "1"[FieldConverter(ConverterKind.Boolean)]publicboolShipped;// Takes as true the string "verdad" and as false the string "mentira" (case insensitive)[FieldConverter(ConverterKind.Boolean,"Verdad","MenTiRa")]publicboolShipped;// 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")]publicboolShipped;// Takes as true the string "X" and as false the string "-"[FieldConverter(ConverterKind.Boolean,"X","-")]publicboolShipped;
Best Practices Analyzer and Quick Fixes for the library
This Roslyn Analyzer helps you to use the library in the right way.
For example when you use a non generic engine the analyzer suggest you to use the generic version:
Quick Fixes
Recommends 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
Check that record class contains valid record attributes
Check that record class contains any field
Convert engine.ReadFile in async version with foreach
Global Install
Install the extension and it will be available for all projects:
The attribute was renamed to align with the real meaning
IComparableRecord<T> => IComparable<T>
We will remove the custom compararer and use the framework one
This release has little breaking changes:
[FieldIgnored] => [FieldHidden]
The attribute was renamed to align with the real meaning
IComparableRecord<T> => IComparable<T>
We will remove the custom compararer and use the framework one
INotifyRead and INotifyWrite now are non generic
In older versions when you implemented notifications via interfaces you must provide the same type of Record
to get proper notification. From 3.1 you use them with out <> and the same is valid for the method signature:
