New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Need of a quick start tutorial #932

Open
dshevani opened this Issue Feb 26, 2018 · 11 comments

Comments

Projects
9 participants
@dshevani

dshevani commented Feb 26, 2018

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

This comment has been minimized.

Show comment
Hide comment
@JoshClose

JoshClose Feb 26, 2018

Owner

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

If so, what was confusing about it?

Owner

JoshClose commented Feb 26, 2018

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

If so, what was confusing about it?

@JoshClose JoshClose added the question label Feb 26, 2018

@travista22

This comment has been minimized.

Show comment
Hide comment
@travista22

travista22 Apr 5, 2018

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

travista22 commented Apr 5, 2018

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

@JimWolff

This comment has been minimized.

Show comment
Hide comment
@JimWolff

JimWolff Apr 6, 2018

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.

JimWolff commented Apr 6, 2018

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 JoshClose added documentation and removed question labels Apr 10, 2018

@JoshClose

This comment has been minimized.

Show comment
Hide comment
@JoshClose

JoshClose Apr 10, 2018

Owner

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.

Owner

JoshClose commented Apr 10, 2018

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

This comment has been minimized.

Show comment
Hide comment
@trailmax

trailmax Apr 10, 2018

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!

trailmax commented Apr 10, 2018

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!

@JoshClose JoshClose added this to To do in Issues Apr 11, 2018

@conficient

This comment has been minimized.

Show comment
Hide comment
@conficient

conficient May 23, 2018

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

conficient commented May 23, 2018

@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

This comment has been minimized.

Show comment
Hide comment
@KishorPatel01

KishorPatel01 Jun 25, 2018

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?

KishorPatel01 commented Jun 25, 2018

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

This comment has been minimized.

Show comment
Hide comment
@michaelmmcrae1

michaelmmcrae1 Jul 3, 2018

@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?

michaelmmcrae1 commented Jul 3, 2018

@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

This comment has been minimized.

Show comment
Hide comment
@JoshClose

JoshClose Jul 3, 2018

Owner

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

Owner

JoshClose commented Jul 3, 2018

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

@conficient

This comment has been minimized.

Show comment
Hide comment
@conficient

conficient Jul 6, 2018

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.

conficient commented Jul 6, 2018

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

This comment has been minimized.

Show comment
Hide comment
@1RedOne

1RedOne Aug 29, 2018

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.

1RedOne commented Aug 29, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment