Csvhelper: Need of a quick start tutorial

[dshevani]

Based on first-hand experience and some posts around internet about CsvHelper, it turns out that there is need of 101 or quick start tutorial for using this library. I was participating in hack day and wanted quick way to convert CSV string to/fro .Net objects. This library was promising but we were not able to understand its usage in few minutes.

https://stackoverflow.com/questions/35900927/convert-string-csv-to-list-of-objects

[JoshClose]

Did you not find the documentation useful? http://joshclose.github.io/CsvHelper/reading

If so, what was confusing about it?

[travista22]

Hi Josh, It would be nice to see documented FULL examples/use cases or more context around the examples you laid out.

[JimWolff]

The first lines of the documentation is basicly a full example:
var csv = new CsvReader( textReader ); var records = csv.GetRecords<MyClass>();
unless you think it's missing the using statement with the textreader, other than that you would have to show the content of a csv file and show the class you are mapping it to (which would be the same) that might just make the documentation cumbersome and more unreadable.
Just my own opinion.

[JoshClose]

I'll add a getting started page that goes through a simple but full example. The things missing are basic .NET IO, but it seems many people coming here aren't familiar with that yet.

[trailmax]

Indeed a simple _full_ sample of how to get started would help. I just found myself looking through your source code just to get started and googling "CsvHelper tutorial". As simple as you already have, only make it a complete example. I did scratch my head and mentally asked myself "what is textReader in that 2-liner?".
Don't need to mention IO in every documentation snippet, just once will do it.

And by the way, many thanks for your effort in this lib!

[conficient]

@JoshClose I can add to this as someone who just started using CsvHelper, and had similar issues.

When you start using the library you're trying to figure out how it works and what the approach or philosophy is. The documentation tells you the details but not the basics. It's rather 'zen' :)

One key area is the mapping approach. I have a file with a header and some data. I want to call .GetRecord<RecordType>(), so I want the columns in the CSV to map the the properties of the RecordType. What is CsvHelper's default approach if I don't manually configure it? How does it change if I use AutoMap? What are the restrictions - e.g. does every property have to be present?

Examples

For a class

class RecordType { 
   string Name {get;set;}
   int ID {get;set}
   bool Active {get;set;}
}

and a file

ID, Name
1, Aaa
2, Bbb

Is the column order important? Do I need to create a map for this or can I rely on defaults? Does CsvHelper read the header to determine the column mapping? Does the missing Active column matter? If I create a mapping class, is the order of the Map(x..) statements important, or irrelevant?

Hope this helps.

[KishorPatel01]

I have been using CvsHelper (7.1.0) for quite a while in .Net Core, till I got conversion error on GetRecords. The CsvHelper exception object (CsvHelperException ) has no information. I would like to get this record so that I can log it.

I tried to use configuration parameters, such as:
reader.Configuration.ReadingExceptionOccurred = exception => {
exception.Message.Dump();
or other parameters, csv.Configuration.IgnoreReadingExceptions = true;
but it says IgnoreReadingExceptions does not exists.

What may be going wrong? Is there a working documented example?

[michaelmmcrae1]

@JoshClose - to re-iterate... there needs to be more basic examples.
For example - conficient's question above is great - there's no relevant answers to those questions in the documentation.

Even just what does Map(p => p.Name) do? Does it try to find a Header with the exact name "Name"? Or does it go by index i.e. if this is the second Map call, does it try to use the 2nd input col?

[JoshClose]

@michaelmmcrae1 So you would like the default settings explicitly call out here? https://joshclose.github.io/CsvHelper/mapping

[conficient]

I'll give you an example. In https://joshclose.github.io/CsvHelper/mapping#auto-mapping

Auto mapping will traverse the object graph and create member mappings for you using defaults.

Here are my questions about this:

• What are the defaults?
• Does it map every header entry to a property in the class?
  
  
  
  • If I have headers which don't have a mapped property, do these get ignored? Or does it raise an error?
  
  
  • If I have additional properties in the class that are not mapped, is that okay?
  
  
• Is the mapping case sensitive (does "name" in header map to .Name) ?
• If the header text has a space, or another characters that are not valid in a property name (e.g. % $ - etc) does this cause an error, or try to convert to (say) underscore?
  
  
  
  • Can I use AutoMap and then override just a single mapping? (e.g. a single column needs a manual mapping, all the others are fine)
  
  

Hopefully you can see the sort of questions a newbie like me might ask about the library.

Here is a case in point. I have an import routine for a supplier datafile using your excellent library. This month they changed the format to add a new column (but containing data I didn't need). I loaded up my code expecting the unit test to fail when I gave it the file to test, but it worked fine!

So I guess that extra columns that are not mapped are ignored? However, that raises a question: in some cases I might want that behaviour to be reversed - so that a format change would throw an error.

[1RedOne]

It's basically impossible for you to assume too little knowledge of the folks who will be using your tool. Like myself, I've got practically no idea what I'm doing here.

I'd love to see these two scenarios covered:

• Given a simple CSV file (with an example of the CSV file), here's how to parse the results and display the results back to the user as an HTML Table or MVC Grid, without using mapping
• And then the above with step by step of how a mapping class is made and used

Basically the docs are great for someone who has a clue in C#. Sadly, most of us are totally clueless.

[frownbreaker]

These are great examples of writing and reading respectively

• http://carlosferreira.com/category/technology/c/ for
• http://carlosferreira.com/reading-csv-files-using-csvhelper-package-c-ienumerable/

In each post, there are code snippets narrative and critically stand-alone projects with data and complete visual studio solutions.

Speaking as one of those with "too little knowledge" complete working solutions like the contents of the zip files at the end of each of the above posts were useful as most of the problems for me were simple things like the using statements, and trivial project/environment related items that trip some folk up, especially those new to .Net and Visual Studio. The problem with code snippets is that they are shorthand, this is fine but for some users like myself, a full working project provides an operational example that is standalone. We can tinker with this to see how things work, and even breaking changes are instructive.

Happy to draft a wiki page for Noobs if that would help or just include links to the 2 posts above that I found useful in the project readme / getting started for noobs.

[JoshClose]

I immediately see some issues with those examples unfortunately.

I am definitely planning on making more comprehensive tutorials on how to do things. I won't be explaining basic programming or basic C#, though I may link to documentation.

[niico100]

I'm totally new to CsvHelper. I'm trying to write a generic collection to a CSV file. Your tool looks great - but on the first page of the documentation IMHO there should be a full .cs code example - with a using at the top - that also writes to a CSV file on disk.

Code I can copy and past that just works.

Sure I can work all this out but it would be trivial to include a full example like the above and save a lot of people 10-60 minutes of searching around to remember / learn how to do these things. You can also ensure they do things in the correct way.

It's not about explaining basic programming - it's just about providing a fully working example for convenience and, specially so beginners, actually implement the library correctly.

[JoshClose]

Yes. I'm working on some new documentation that will contain a lot of examples.

[dgomez-listrak]

I'm having trouble figuring out how to deal with a situation where we have a minimum set of required columns with a header, but need to support any combination of like... 6 required 5 optional. I could probably hack something together using the .Read() and GetField() methods but thought there might be a better way.

[JoshClose]

There is a mapping option Optional.

void Main()
{
    var s = new StringBuilder();
    s.AppendLine("Id");
    s.AppendLine("1");
    s.AppendLine("2");
    using (var reader = new StringReader(s.ToString()))
    using (var csv = new CsvReader(reader))
    {
        csv.Configuration.Delimiter = ",";
        csv.Configuration.RegisterClassMap<TestMap>();
        csv.GetRecords<Test>().ToList().Dump();
    }
}

public class Test
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public class TestMap : ClassMap<Test>
{
    public TestMap()
    {
        Map(m => m.Id);
        Map(m => m.Name).Optional();
    }
}

[dgomez-listrak]

I stumbled across this option as you were writing the response. Solves my problems! thank you!

[TheConsciousness]

Great work on the tool, but I too am slowly getting my bearings with the documentation. I wasn't aware that I would need a class, which I'm sure would have been elementary if I were familiar with these concepts.

[JoshClose]

@TheConsciousness Need a class for what?

[jzabroski]

@JoshClose Have you checked out the new dotnet global tool Try.NET lately?

I think that should be how the tutorial works, and I would be open to contributing.

[liamlaverty]

Something that'd be handy to add to this quickstart tutorial or an FAQ section would be how Encoding is handled outside of CSVHelper both reading and writing. A large number of the questions in the Stack Overflow tag CSVHelper reference encoding either in the question or accepted response.

[JoshClose]

There is a quick start "getting started" section. There is a an examples section that contains a "prerequisites" section for .NET things you need to know to use CsvHelper.

[1RedOne]

Just wanted to say, the stuff in the Getting Started section is exactly what I was looking for like two years ago when I first upvoted this. Thanks for doing it, I'm sure future folks will benefit greatly from it :)