fsprojects / FSharp.Data

F# Data: Library for Data Access
https://fsprojects.github.io/FSharp.Data
Other
817 stars 287 forks source link

DOC: explaining EmbeddedResource parameter would be super helpful #1315

Open daz10000 opened 4 years ago

daz10000 commented 4 years ago

I lost a few hours of my life to syntax for the embedded resource parameter, and thought it might be helpful to document what was missing. I worked out some of it from bug reports and random experimentation and finally peeking into a DLL, but some docs would have saved an enormous amount of time

explain

it's probably also worth explaining what happens if you don't do this (you get a really cryptic problem from the type provider using the path as an example of the CSV file and it's really evil because it works in the first DLL but the dependent DLL just gets a single CSV column with the path as its name.

Right now the only resources you have are bug reports where the mechanism wasn't working temporarily, and partial examples. One simple end to end example, and possibly references to tools like ildasm or other things for interest affecting the embedded resource name mangling would be helpful.

Overall code works wonderfully, but this is a pretty nasty pit to fall into which could be avoided with a paragraph of documentation.

dsyme commented 4 years ago

@daz10000 Could you write out a step by step to recreate the cryptic problems mentioned?

Thanks

daz10000 commented 4 years ago

fair call! That's a pretty cryptic complaint.I would be happy to send a pull request for some better documentation but wasn't quite sure where to put this. I think the issue is applicable to each of the type providers, but I encountered it with the CSV provider.

To reproduce

namespace ProjB

type CapitalCSV = FSharp.Data.CsvProvider<"example/MyCSV.csv",HasHeaders=true>

module Say =
    let rows = CapitalCSV.Load("myfile.csv").Rows
    for row in rows do
        printfn "Capital=%s" row.Capital

image

Maybe this could be converted into a short example and put somewhere central - it's applicable to all the providers. Maybe this is common knowledge but I had to work out the syntax for the embedded resource experimentally peeking inside the dll itself and looking at hints from other bug reports.

Also attaching full working example which might be handy. It's pinned to netcore3.1 in global.json just because I have netcore 5 preview floating around and it's breaking a few things but should be fine without the global.json files in practice.

TPPathDemo.zip

nhirschey commented 3 years ago

@daz10000, see here (https://github.com/fsprojects/FSharp.Data/pull/1334) for some new documentation of this on the JsonProvider. That’s at least 3 of us hitting this cryptic info in the past 12 months.

Maybe you can do a pull request adding similar info to the CsvProvider docs. Or, a new short EmbeddedResource.fsx document using FSharp.Formatting explaining your response to Don above for JsonProvider and CsvProvider? Your explanation of the paths/Library naming issue is more complete than the new JsonProvider doc text. And it makes more sense to have one full explanation as you mention covering all the providers and then link to it from the other provider docs.

nhirschey commented 3 years ago

@daz10000, another related issue https://github.com/fsprojects/FSharp.Data/issues/1191