CSV Helper
CSV Helper
CSV Helper
Reading
Writing
Mapping
Configuration
Type Conversion
(https://github.com/joshclose/csvhelper)
A .NET library for reading and writing CSV files. Extremely fast, flexible and easy to use. Supports reading and writing of custom class objects.
Getting Started
To install CsvHelper, run the following from the Package Manager Console. (http://docs.nuget.org/docs/start-here/using-the-package-manager-console) 1I n s t a l l P a c k a g eC s v H e l p e r
Reading
Reading all records
Reading is setup to be as simple as possible. If you have a class structure setup that mirrors the CSV file, you can read the whole file into an enumerable. 1v a rc s v=n e wC s v R e a d e r (t e x t R e a d e r) ; 2v a rr e c o r d s=c s v . G e t R e c o r d s < M y C l a s s > ( ) ; If you want to customize how the CSV file maps to your custom class objects, you can use mapping.
The IEnumerable<T> that is returned will yield results. This means that a result isn't returned until you actually access it. This is handy because the whole file won't be loaded into memory, and the file will be read as you access each row. If you do something like Count() on the IEnumerable<T>, the whole file needs to be read and you won't be able to iterate over it again without starting over. If you need to iterate the records more than once (like using Count), you can load everything into a list and the work on the data. 1v a rc s v=n e wC s v R e a d e r (t e x t R e a d e r) ; 2v a rr e c o r d s=c s v . G e t R e c o r d s < M y C l a s s > ( ) . T o L i s t ( ) ;
TryGetField
If you might have inconsistencies with getting fields, you can use TryGetField. 1v a rc s v=n e wC s v R e a d e r (t e x t R e a d e r) ; 2w h i l e (c s v . R e a d ( )) 3{ 4 i n ti n t F i e l d ; 5 i f (! c s v . T r y G e t F i e l d (0 ,o u ti n t F i e l d)) 6 { 7 / /D os o m e t h i n gw h e ni tc a n ' tc o n v e r t . 8 } 9}
Writing
Writing all records
Writing is setup to be as simple as possible. If you have a class structure setup that mirrors the CSV file, you can write the whole file from an enumerable.
1v a rc s v=n e wC s v W r i t e r (t e x t W r i t e r) ; 2c s v . W r i t e R e c o r d s (r e c o r d s) ; If you want to customize how the CSV file maps to your custom class objects, you can use mapping.
Mapping
Auto Mapping
If you don't supply a mapping file, auto mapping will be used. Auto mapping will map the properties in your class in the order they appear in. If the property is a custom class, it recursively maps the properties from that class in the order they appear in. If the auto mapper hits a circular reference, it will stop going down that reference branch.
Reference Map
Reference maps are used to map a property that is a custom class to it's own mapping that maps those properties to several CSV columns. You can nest reference maps as many layers deep as you like.
1p u b l i cc l a s sP e r s o n M a p:C s v C l a s s M a p < P e r s o n > 2{ 3 p u b l i co v e r r i d ev o i dC r e a t e M a p ( ) 4 { 5 M a p (m= >m . I d) ; 6 M a p (m=>m . N a m e) ; 7 R e f e r e n c e s < A d d r e s s M a p > (m= >m . A d d r e s s) ; 8 } 9} 1 0 1 1p u b l i cc l a s sA d d r e s s M a p:C s v C l a s s M a p < A d d r e s s > 1 2{ 1 3 p u b l i co v e r r i d ev o i dC r e a t e M a p ( ) 1 4 { 1 5 M a p (m= >m . S t r e e t) ; 1 6 M a p (m= >m . C i t y) ; 1 7 M a p (m= >m . S t a t e) ; 1 8 M a p (m= >m . Z i p) ; 1 9 } 2 0}
Index
When mapping by index you specify the index of the CSV column that that you want to use for that property. 1p u b l i cc l a s sM y C l a s s M a p:C s v C l a s s M a p < M y C l a s s > 2{ 3 p u b l i co v e r r i d ev o i dC r e a t e M a p ( ) 4 { 5 M a p (m= >m . I d) . I n d e x (0) ; 6 M a p (m= >m . N a m e) . I n d e x (1) ; 7 } 8}
Name
When mapping by name you specify the name of the CSV column that you want to use for that property. For this to work, the CSV file must have a header record. The name you specify must match with the name of the header record. 1p u b l i cc l a s sM y C l a s s M a p:C s v C l a s s M a p < M y C l a s s > 2{ 3 p u b l i co v e r r i d ev o i dC r e a t e M a p ( ) 4 { 5 M a p (m= >m . I d) . N a m e (" T h eI dC o l u m n ") ; 6 M a p (m= >m . N a m e) . N a m e (" T h eN a m eC o l u m n ") ; 7 } 8}
Name Index
Sometimes CSV files have multiple columns with the same name. When this happens, you can use NameIndex to specify which column name you are referring to. The NameIndex is NOT the column in the CSV file. 1p u b l i cc l a s sM y C l a s s M a p:C s v C l a s s M a p < M y C l a s s > 2{ 3 p u b l i co v e r r i d ev o i dC r e a t e M a p ( ) 4 { 5 M a p (m= >m . F i r s t N a m e) . N a m e (" N a m e ") . N a m e I n d e x (0) ; 6 M a p (m= >m . L a s t N a m e) . N a m e (" N a m e ") . N a m e I n d e x (1) ; 7 } 8}
Ignore
Currently this is not used. Mapping will only map properties that you specify. In the future there will be an
option to auto map within a class map, and any mappings explicitly stated will override the auto mapped ones. When this happens, ignore will be used to ignore a property that was auto mapped.
Default
Default is used to set a default value you want to use if the field is empty. 1p u b l i cc l a s sM y C l a s s M a p:C s v C l a s s M a p < M y C l a s s > 2{ 3 p u b l i co v e r r i d ev o i dC r e a t e M a p ( ) 4 { 5 M a p (m= >m . I d) . I n d e x (0) . D e f a u l t (1) ; 6 M a p (m= >m . N a m e) . I n d e x (1) . D e f a u l t (" U n k n o w n ") ; 7 } 8}
Type Converter
If the value of the CSV field can't automatically be converted into the type of the property, you can specify a custom CsvHelper.TypeConversion.ITypeConverter to be used to convert the value. See Type Conversion for documentation on how to create a custom type converter. 1p u b l i cc l a s sM y C l a s s M a p:C s v C l a s s M a p < M y C l a s s > 2{ 3 p u b l i co v e r r i d ev o i dC r e a t e M a p ( ) 4 { 5 M a p (m= >m . I d) . I n d e x (0) . T y p e C o n v e r t e r < M y I d C o n v e r t e r > ( ) ; 6 } 7}
Convert Using
When all else fails, you can use ConvertUsing. ConvertUsing allows you to write custom code inline to convert the row into a single property value.
1p u b l i cc l a s sM y C l a s s M a p:C s v C l a s s M a p < M y C l a s s > 2{ 3 p u b l i co v e r r i d ev o i dC r e a t e M a p ( ) 4 { 5 / /C o n s t a n tv a l u e . 6 M a p (m= >m . C o n s t a n t) . C o n v e r t U s i n g (r o w= >3) ; 7 / /A g g r e g a t eo ft w or o w s . 8 M a p (m= >m . A g g r e g a t e) . C o n v e r t U s i n g (r o w= >r o w . G e t < i n t > (0)+ r o w . G e t < i n t > (1)) ; 9 / /C o l l e c t i o nw i t has i n g l ev a l u e . 1 0 M a p (m= >m . N a m e s) . C o n v e r t U s i n g (r o w= >n e wL i s t < s t r i n g > { r o w . G e t < s t r i n g > (" N a m e ")}) ; 1 1 / /J u s ta b o u ta n y t h i n g . 1 2 M a p (m= >m . A n y t h i n g) . C o n v e r t U s i n g (r o w= > 1 3 { 1 4 / /Y o uc a nd oa n y t h i n gy o uw a n ti nab l o c k . 1 5 / /J u s tm a k es u r et or e t u r nt h es a m et y p ea st h ep r o p e r t y . 1 6 }) ; 1 7 } 1 8}
Configuration
Allow Comments
This flag tells the parser whether comments are enabled. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . A l l o w C o m m e n t s=f a l s e ;
Auto Map
This is used to generate a CsvClassMap from a type automatically without a fluent class mapping. This will try to map all properties including creating reference maps for properties that aren't native types. If the auto mapper detects a circular reference, it will not continue down that path. 1v a rg e n e r a t e d M a p=c s v . C o n f i g u r a t i o n . A u t o M a p < M y C l a s s > ( ) ;
Buffer Size
The size of the internal buffer that is used when reader or writing data to and from the TextReader and TextWriter. Depending on where your TextReader or TextWriter came from, you may want to make this value larger or smaller. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . B u f f e r S i z e=2 0 4 8 ;
Comment
The value used to denote a line that is commented out. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . C o m m e n t=' # ' ;
Count Bytes
A flag that will tell the parser to keep a count of all the bytes that have been read. You need to set Configuration.Encoding to the same encoding of the CSV file for this to work properly. This will also slow down parsing of the file. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . C o u n t B y t e s=f a l s e ;
Culture Info
The culture info used to read and write. This can be overridden per property in the mapping configuration. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . C u l t u r e I n f o=C u l t u r e I n f o . C u r r e n t C u l t u r e ;
Delimiter
The value used to separate the fields in a CSV row. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . D e l i m i t e r=" , " ;
Encoding
The encoding of the CSV file. This is only used when counting bytes. The underlying TextReader and TextWriter will have it's own encoding that is used. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . E n c o d i n g=E n c o d i n g . U T F 8 ;
1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . I g n o r e H e a d e r W h i t e S p a c e=f a l s e ;
Ignore Quotes
A flag that tells the parser to ignore quotes as an escape character and treat it like any other character. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . I g n o r e Q u o t e s=f a l s e ;
Maps
You are able to access the registered class maps. 1v a rm y M a p=c s v . C o n f i g u r a t i o n . M a p s [ t y p e o f (M y C l a s s) ] ;
Quote
The value used to escape fields that contain a delimiter, quote, or line ending.
Quote No Fields
A flag that tell the writer whether all fields written should not have quotes around them; regardless if the field contains anything that should be escaped. Both QuoteAllFields and QuoteNotFields cannot be true at the same time. Setting one to true will set the other to false. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . Q u o t e A l l F i e l d s=f a l s e ;
Trim Fields
This flag tells the reader to trim whitespace from the beginning and ending of the field value when reading. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . T r i m F i e l d s=f a l s e ;
Trim Headers
This flag tells the reader to ignore white space from the beginning and ending of the headers when matching the columns to the properties by name. 1/ /D e f a u l tv a l u e 2c s v . C o n f i g u r a t i o n . T r i m H e a d e r s=f a l s e ;
2.2.1
Bug Fixes Fixed issue with trimming fields not working under one path.
2.2.0
Features Added Row property to ICsvReader. Config option to trim headers and values when reading.
2.1.1
Bug Fixes Fixed issue when WillThrowOnMissingField is off and exception was still being thrown.
2.1.0
Features Made RegisterClassMap overload with CsvClassMap instance public.
2.0.1
Bug Fixes Made a WinRT Any CPU build and removed the arch specific WinRT builds.
2.0.0
Features Added parser configuration to ignoring quotes and treating them like any other character. Added CsvFactory to create ICsvParser, ICsvReader, and ICsvWriter classes. This is useful when you need to unit test code that uses CsvHelper since these 3 classes require a TextReader or TextWriter to work. All assembly versions are strong named but will use a single version of 2.0.0.0. The file version and NuGet versions will change with every release. Removed class type constraint from reading and writing. Added non-generic class mapping overload. WriteRecords param changed from IEnumerable<object> to non-generic IEnumerable. Value types can be read and written instead of just custom classes. Indexes are automatically set and incremented when mapping in order of the Map and Reference calls. Auto mapping with circular reference detection. Config option to ignore spaces in header names. Fixed exception handling. Exception are no longer wrapped. Exception.Data["CsvHelper"] contains CsvHelper specific exception info. Row exception can be skipped during GetRecords. Renamed IsStrictMode to WillThrowOnMissingField. Window Phone 7 & 8 builds. Auto mapping will use defined maps if available. Type converter options. Added IEnumerable converter that throws an exception so people will know that converting to/from and enumerable is not supported instead of getting a cryptic error message. Dynamic support for reading and writing. Multiple maps can be supplied. Renamed InvalidateRecordCache to ClearRecordCache. Recursive reference mapping down the whole mapping tree. Configuration.CultureInfo was added in place of Configuration.UseInvariantCulture. Bug Fixes Getting the exception helper message failed when writing because no parser is available. WriteRecords Dynamic invoke had wrong parameter count. GetField( string ) was not returning null if the header is not found. CsvBadDataException when there were extra columns in the row. Raw record corruption.
1.17.0
Features Ignore properties that can't be set in attribute mapping.
Made TypeConverterFactory thread safe. Added remove converter method. Bug Fixes Issue with writer exception in WinRT.
1.16.0
Features Change TypeConverterFactory to use a set of cache type converters so global type converters can be used. Added GetField<T, TConverter> overloads. Changed all Activator.CreateInstance calls to use compiled expression trees to create them instead. Changed mapping for ConvertUsing to accept a Func so a block expression can be used.
1.15.0
Features Support for Silverlight 4 & 5. Bug Fixes Issue where writing with Configuration.QuoteAllFields enabled will not quote the quotes inside the field. Issue with WinRT not building after pull request merge.
1.14.0
Features Parse full line on read. This allows for the parser to retain the whole unchanged raw CSV lin on a read. Changed delimiter config from a char to a string. Iterating records multiple times will throw a CsvReaderException. This is to help stop confusion when 0 results are returned the second iteration. Bug Fixes Issue where EnumConverter isn't created correctly from the TypeConverterFactory. Issue with updating count for all closing quotes.
1.13.0
Features Configuration to always not quote all fields. WriteHeader method is public. Added enum converter. Bug Fixes Issue with boolean converter returning true for "no" value. Issue with GetMethod in WinRT.
1.12.1
Bug Fixes Isse where an exception was being thrown when reading all records multiple times.
1.12.0
1.11.0
Features Better exception information added to CsvBadDataException.
1.10.0
Features Mapping property for CreateUsing which allows user to specify how the property gets created.
1.9.2
Bug Fixes Issue with skipping empty records.
1.9.1
Bug Fixes Issue with detecting column count changes.
1.9.0
Features Added properties to CsvReaderException to give more information about the error. Ability to skip empty records based on config settings. Getting by index that doesn't exist will give a default or CsvMissingFieldException. Made column count detection a config setting. Map option for constructing the row object. Throw exception when inconsistent column lengths are detected. String.Format support in CsvWriter. Excel compatible parsing. Parser can keep track of the byte position using an encoding so a user cna seek to a stream and start reading from there. Bug Fixes Fixed bug with column count detection. Issue with double counting the closing quote. Issue where parsing was incorrect when the last row didn't have a CRLF at the end. Issue with error messages.
1.8.0
Features Writer overload for shouldQuote when writing a field. Ability for using alternative names for headers in the configuration. Better error messages.
1.7.0
Features
Configuration to quote all fields when writing. Parser keeps a char count of where it's at. Bug Fixes Fixed subclass issue by having the reader and writer use interfaces instead of concrete classes.
1.6.0
Features Custom boolean type converter that can convert from 1 and 0 besides the normal conversion. Property map configuration to set a default value. CsvWriter no longer flushes to the output stream after every record. Non-generic overloads for reading, writing, and attribute mapping. Invalidate record cache will clear the properties list.
1.5.0
Features Support .NET 2.0 and 3.5 builds.
1.4.0
Features Case insensitive header matching.
1.3.0
Features Removed CsvHelper class. Property reference mapping. One level deep.
1.2.0
Features Support for multiple duplicate header names.
1.1.2
Bug Fixes Issue when using a readonly or writeonly stream and disposing causes an exception.
1.1.1
Features Updated CsvHelper.cs to allow for readonly and writeonly stream. Bug Fixes Fixed DateTimeConverter issue where a white space string would return a DateTime.MinValue instead of null.
1.1.0
Features Changed .NET 3.5 project to client profile.
1.0.0
Features Changed strict mode to default to true. Renamed strict mode configuration property. Changed reader to not throw an exception when there are duplicate header records unless in strict mode. Bug Fixes Fixed bug where if there is no line ending at the end of the file, the last field would be null instead of an empty string. Fixed configuration references and constructor signatures.
0.16.0
Features Added configuration option for using CultureInvariant to read/write. Updated the reader/writer to use the config option. Both CsvReader and CsvWriter are using Local culture when converting from/to strings. CsvClassMap without generic argument.
0.15.0
Features Changed TryGetField<T> to do a low level check instead of jsut wrapping in try/catch blocks. Removed non generic TryGetField methods. Formatting changes. Changed CsvParser to use the Configuration.Comment char instead of #. Bug Fixes Fixed indentation error caused by new constructor in CsvPropertyMap.
0.14.0
Features Changed GetRecords<T> to return IEnumerable<T>. Added convenience constructor to CsvPropertyMap. Major configuration overhaul. Changed end of file check to be more low level. Final record is returned if there is a trailing delimiter. Added an exception re-throw to parsing that tells the line and character number. Added ability to change what the quote char is. Added CSV specific exceptions. Bug Fixes Fix for issue when CsvHelper uses CurrentCulture instead of InvariantCulture.
0.13.0
Features Changed StreamReader to TextReader to be more generic.
0.12.0
Features Added option to have a commented out line using '#' as the first character of the line. Bug Fixes Fixed issue with spaces in non-quoted field.