.NET Platform Standard Document - Some Ideas to improve it

[tthiery]

I was reading the ".NET Platform Standard" document. I liked it a lot, but there are some details where I would love some clarification in the document

• It is about the Platform Standard. Nevertheless, many will use the netstandard TFMs for their libraries. So when speaking of "Reference Assembly" and "Implementation Assembly", I think we need a very clear separation between a library targeting a netstandard which is
  • distributed by an normal library developer which is portable (he delivers a nuget package with a ref and a implementation assembly (or only a impl?))
  • distributed by an normal library developer which is not portable (bait and switch)
  • a library like System.IO which is 99% delivered as part of the platform which is not portable (which has a ref assembly and a implementation assembly per platform, in the platform), but nevertheless has a NuGet package. How does that work (only ref?).
  • a library like System.Xml.XDocument which is part of the CoreFx, which is portable which future platforms should just use via NuGet but some older platforms may still have as a implementation assembly in the platform.
• I would add a line stating that targeting a lower platform standard is preferable.
• In the CoreFx list a classification which library is portable, sometimes portable and always platform specific would be nice
• A word about how the NuGet packages of the netstandard (e.g. System.IO) build only with their refs and their implementation assemblies as part of the platforms (they are build and shipped with them, e.g. in coreclr). I think it should be clarified that the public NuGet which reflect platform features only have refs.

@davidfowl @AArnott

ps: I am surely not 100% accurate here. I just think myself into nuget3, DNX, corefx, coreclr, etc. and jump on any documentation I get.

[davidfowl]

@tthiery excellent suggestions!

[davidfowl]

distributed by an normal library developer which is portable (he delivers a nuget package with a ref and a implementation assembly (or only a impl?))

distributed by an normal library developer which is not portable (bait and switch)

This will be mostly lib only, nothing will change from today. The only time you need ref is for bait and switch.

[tthiery]

understood. "Today" is quite new for many. PCLs usage and NuGet package creation is new for many enterprise devs ;)

[tthiery]

@davidfowl I see the "NETStandard.Library" dependency showing up everywhere instead of concrete dependencies. That is a new twist. Maybe also worth adding to the document (including how it works in the nuget hierarchy ... just start to understand that a minute ago ;)).

[davidfowl]

/cc @richlander @Petermarcu

[RichiCoder1]

I see the "NETStandard.Library" dependency showing up everywhere instead of concrete dependencies. That is a new twist.

This has been throwing me off too. I like it, but it breaks from a lot of written docs.

[terrajobst]

This doc has been superseded with the documentation found in https://github.com/dotnet/standard.