Add FAQ #62

terrajobst · 2016-10-14T00:32:58Z

This fixes #35.

This moves the .NET Standard support matrix out of the .NET Standard 2.0 spec and adds searchable refs and diffs for the existing .NET Standard versions.

In addition, this adds the FAQ that answers the questions folks asked on our blog and in issue #35.

@weshaggard, give a quick read to see whether that works.

dnfclas · 2016-10-14T00:33:01Z

Hi @terrajobst, I'm your friendly neighborhood .NET Foundation Pull Request Bot (You can call me DNFBOT). Thanks for your contribution!
You've already signed the contribution license agreement. Thanks!

The agreement was validated by .NET Foundation and real humans are currently evaluating your PR.

TTYL, DNFBOT;

mairaw · 2016-10-14T00:37:59Z

docs/faq.md

+* [Introducing .NET Standard][netstandard-post] blog post
+* [Intro to .NET Standard](https://channel9.msdn.com/Blogs/Seth-Juarez/What-is-NET-Standard) video
+* [Q&A](https://channel9.msdn.com/Shows/On-NET/Immo-Landwerth-Net-Standard) video
+


should we link to the docs too?

No idea why this didn't occur to me. Fixed.

mairaw · 2016-10-14T00:38:39Z

docs/faq.md

+## Is the API set of a .NET Standard version fixed?
+
+Yes. A specific version of .NET Standard remains frozen once shipped. New APIs
+will first become availabe in specific .NET platforms, such as .NET Core. If we


typo: availabe

mairaw · 2016-10-14T00:38:59Z

docs/faq.md

+The primary reason we expose this type in .NET Standard is because the usage is
+fairly high and typically not associated with creating new app domains but for
+interacting with the current app domain, such as registering an unhandled
+exception handla or asking for the application's base directory.


typo: handla

I swear I know how handler is being spelled 😄 . Fixed.

Or maybe you're becoming a gansta 😄

mairaw · 2016-10-14T00:39:10Z

docs/faq.md

+## Is `System.Data` part of .NET Standard?
+
+.NET Standard will contain the abstractions (`DbProvider`,
+`DbProviderFactories`, `DbConnection`, `IDbConnection` etc) as well as the the


mairaw · 2016-10-14T00:41:37Z

docs/faq.md

+APIs will not be supported everywhere and throw `PlatformNotSupportedException`.
+While that isn't ideal, it's much simpler than the alternatives, which are:
+
+* Using `#if`, i.e. cross-compile


i.e. : Don't use. Use that is instead. (MSFT style guide) although I'm not completely sure this would be the right meaning here

mairaw · 2016-10-14T00:42:49Z

docs/faq.md

+
+There is nothing language specific about .NET Standard. From a language view
+point, the only tie-in to .NET Standard are the language-specific runtime APIs
+(e.g. `Mirosoft.CSharp`, `Microsoft.VisualBasic`, `FSharp.Core` etc) and the


e.g. : Don't use. Use for example instead. (MSFT style guide)

nit: etc -> , etc.

Both fixed throughout

mairaw · 2016-10-14T00:44:48Z

docs/versions.md

+
+## How do I know which .NET Standard version I should target?
+
+When choosing a .NET Standard version you should consider this trade-off:


nit: missing comma after version

mairaw · 2016-10-14T00:44:57Z

docs/versions.md

+
+So generally speaking, you should target the lowest version you get away with.
+To inform your decision, you should consider the compatibility matrix and the
+APIs additions linked fromt the table above.


typo: fromt

mairaw · 2016-10-14T00:45:12Z

docs/versions.md

+   changes between versions.
+2. **Immutable**. Once shipped, .NET Standard versions are frozen.
+
+New APIs will first become availabe in specific .NET platforms, such as .NET


typo: availabe

mairaw · 2016-10-14T00:46:40Z

docs/versions.md

+To inform your decision, you should consider the compatibility matrix and the
+APIs additions linked fromt the table above.
+
+# Versining rules


typo: Versining

akoeplinger · 2016-10-14T11:31:50Z

docs/faq.md

+
+## Why is JSON.NET not part of .NET Standard?
+
+Today, the best library for dealing with JSON is JSON.NET. But by adding it to


"The best" is debatable as many people prefer other libraries like ServiceStack.Text, Jil, SimpleJson for various reasons and whether it's the best or not is irrelevant for the argument you're trying to make in this section.

"One of the best" or "One of the most popular" is better IMHO.

Fair enough

akoeplinger · 2016-10-14T11:36:37Z

docs/faq.md

+## Will Unity implement .NET Standard?
+
+Yes. We're working with Unity to make sure this is a smooth experience. In
+general, since Unity is a fork of Mono and it will mostly get .NET Standard


remove and

akoeplinger · 2016-10-14T11:37:45Z

docs/faq.md

+## What's the difference between .NET Standard Library and .NET Platform Standard?
+
+These were terms we used in earlier discussions. We only have one concept today
+called *.NET Standard*.


What about the NETStandard.Library nuget package people see in project.json today? Will this go away?

We don't know yet; we'll mostly likely reuse that name for the NuGet package but we don't know yet how that is showing up in .csproj. That's why I left it out for now.

akoeplinger · 2016-10-14T11:38:27Z

docs/faq.md

+These were terms we used in earlier discussions. We only have one concept today
+called *.NET Standard*.
+
+## Can you explain the assemblies and type fowarding in more detail?


akoeplinger · 2016-10-14T11:43:45Z

docs/versions.md

+|.NET Framework             |&rarr;|  4.5 | 4.5.1|   4.6|&rarr;|&rarr;|&rarr;| 4.6.1|
+|Mono                       |&rarr;|&rarr;|&rarr;|&rarr;|&rarr;|&rarr;|&rarr;| vNext|
+|Xamarin.iOS                |&rarr;|&rarr;|&rarr;|&rarr;|&rarr;|&rarr;|&rarr;| vNext|
+|Xamarin.Android            |&rarr;|&rarr;|&rarr;|&rarr;|&rarr;|&rarr;|&rarr;| vNext|


The following Mono/Xamarin versions supported netstandard1.6:

Mono 4.6

Xamarin.iOS 10.0 (Cycle 8)

Xamarin.Android 7.0 (Cycle 8)

Cool, will fix those.

akoeplinger · 2016-10-14T11:53:07Z

docs/versions/netstandard1.0.md

@@ -0,0 +1,15 @@
+# .NET Standard 1.0
+
+* [APIs](netstandard1.0_ref.md)


Commenting here since GH won't let me comment on this file:

You could do csharp instead of diff in the _ref files to get nice syntax highlighting for C#.

Good call! Fixed.

This fixes #35.

svick · 2016-10-14T13:55:52Z

docs/faq.md

+## I still don't get it. Can you provide an analogy that makes sense for a dev?
+
+David Fowler provided a [developer analogy][netstandard-analogy] that explains
+.NET Standard in terms of interfaces and classes.


Should @davidfowl's analogy be updated to include .Net Standard 2.0?

Yes. Filed #63 to track this.

svick · 2016-10-14T14:02:45Z

docs/faq.md

+## How does .NET Standard versioning work?
+
+Think of the .NET Standard versions as concentric circles: higher versions
+incorporate all APIs from previous versions.


I though NS 2.0 does not incorporate all APIs from NS 1.6. Should that be mentioned here?

Now it does :-) See here.

svick · 2016-10-14T14:16:38Z

docs/faq.md

+two different types can live in separate assemblies but we don't have a
+mechanism to split a single type across two different assemblies. In those
+cases, we leave the members on the type and let platforms that cannot
+meaningfully implement them throw `PlatformNotSupportedException`.


I'm confused, above you said that MarshalByRefObject will be exposed, but MarshalByRefObject.CreateObjRef won't. But, if I understand it correctly, this section says that if you expose a type, you also expose all its members.

Assuming others are likely to be confused just like I am, should this be clarified?

svick · 2016-10-14T14:25:47Z

docs/versions.md

+|Universal Windows Platform |&rarr;|&rarr;|&rarr;|&rarr;|  10.0|&rarr;|&rarr;| vNext|
+|Windows                    |&rarr;|   8.0|   8.1|      |      |      |      |      |
+|Windows Phone              |&rarr;|&rarr;|   8.1|      |      |      |      |      |
+|Windows Phone Silverlight  |   8.0|      |      |      |      |      |      |      |


This article does not mention the whole "NS 2.0 is not a superset of NS 1.6" issue at all. Why not?

As a consequence, for example the table implies that .Net Framework 4.6.1 supports .Net Standard 1.6 or that to run on .Net Framework 4.6.1 and .Net Core 1.0, you can target .Net Standard 1.6.

Unless something changed, I think this should not be ignored.

Nevermind, the changes in #61 explain that this is no longer true. Though that means that the "Introducing .NET Standard" blog post linked at the start of the FAQ is now out of date.

This fixes #35.

danmoseley · 2016-10-14T16:39:53Z

docs/faq.md

+
+There is nothing language specific about .NET Standard. From a language view
+point, the only tie-in to .NET Standard are the language-specific runtime APIs
+(e.g. `Mirosoft.CSharp`, `Microsoft.VisualBasic`, `FSharp.Core` etc) and the


typo MIcrosoft

danmoseley · 2016-10-14T16:44:20Z

docs/versions.md

+
+* The columns represent .NET Standard versions. The header is a link to a
+  document that shows which APIs got added in that version of .NET Standard.
+* The rows indicate which version of a given .NET platform implemens a given


typo implements

akoeplinger · 2016-10-14T17:10:31Z

docs/faq.md

+
+## Why is JSON.NET not part of .NET Standard?
+
+Today, one of the most popular library for dealing with JSON is JSON.NET. But by


~~library~~ libraries

dnfclas added the cla-already-signed label Oct 14, 2016

terrajobst mentioned this pull request Oct 14, 2016

Update .NET Standard 2.0 spec #61

Merged

mairaw reviewed Oct 14, 2016

View reviewed changes

akoeplinger reviewed Oct 14, 2016

View reviewed changes

akoeplinger referenced this pull request Oct 14, 2016

Add FAQ

f85121c

This fixes #35.

svick reviewed Oct 14, 2016

View reviewed changes

Add FAQ

26da6e9

This fixes #35.

danmoseley approved these changes Oct 14, 2016

View reviewed changes

terrajobst force-pushed the terrajobst/faq branch 4 times, most recently from 94c790f to 3268a04 Compare October 14, 2016 17:10

akoeplinger reviewed Oct 14, 2016

View reviewed changes

Address code review feedback

9a32065

terrajobst force-pushed the terrajobst/faq branch from 3268a04 to 9a32065 Compare October 14, 2016 17:16

terrajobst self-assigned this Oct 14, 2016

terrajobst merged commit 4419038 into master Oct 14, 2016

terrajobst deleted the terrajobst/faq branch October 14, 2016 17:18


		## How do I know which .NET Standard version I should target?

		When choosing a .NET Standard version you should consider this trade-off:


		## Why is JSON.NET not part of .NET Standard?

		Today, the best library for dealing with JSON is JSON.NET. But by adding it to

		@@ -0,0 +1,15 @@
		# .NET Standard 1.0

		* [APIs](netstandard1.0_ref.md)


		## Why is JSON.NET not part of .NET Standard?

		Today, one of the most popular library for dealing with JSON is JSON.NET. But by

Add FAQ #62

Add FAQ #62

Conversation

terrajobst commented Oct 14, 2016

dnfclas commented Oct 14, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

terrajobst Oct 14, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

akoeplinger Oct 14, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

terrajobst Oct 14, 2016 •

edited

akoeplinger Oct 14, 2016 •

edited