C# Guide: Explain the language dependency on framework types

[BillWagner]

This stems from comments here regarding the necessity of including the System.ValueTask NuGet package. In particular, this comment:

So it seems that either I've put together some bad information. I was reading that since we are using open source Roslyn to compile C# now that you could write language extensions and have them available as a Nuget package. Basically to enhance any compiling or modifications you wanted to do to C# yourself. With that my understand was that System.ValueTuple was part of the C# 7 language as a side Nuget package. But you're saying, if I'm on the right track, it's actually a .NET framework package (which makes alot more sense). If anyone has a moment and could clarify this up for me I would appreciate it. At least the bit on the C# Nuget packages. I believe I have also relayed some information that I need to re-track.

The mental model should be that the compiler knows how to generate code for all the features. However, some features rely on particular classes or methods in a library. The NuGet packages enable developers that target older frameworks to use the new language features. ValueTuple is one example. Earlier, the async packages included Task and Task extensions that enabled async support for developers targeting earlier versions of the framework.

[agocke]

Regarding

I was reading that since we are using open source Roslyn to compile C# now that you could write language extensions and have them available as a Nuget package. Basically to enhance any compiling or modifications you wanted to do to C# yourself.

This isn't quite correct. True, Roslyn is open source and you can write your own language features, but they still need to be included in the compiler and can't be added via NuGet package. You can add your own diagnostics (warnings/errors) via a Roslyn analyzer NuGet package, but those won't generate any additional code or add any new language features to the compiler. If you would like to write a new language feature for C# you'll need to add it to the compiler and submit a PR to the Roslyn Github repository.

The reason System.ValueTuple.dll exists is that the compiler needs a System.ValueTuple type to reason about tuples. The compiler is actually very agnostic about this type -- it can come from anywhere. You could even write your own type called System.ValueTuple (and System.Runtime.CompilerServices.TupleNamesAttribute) in your source code and the compiler would pick up that type and use it for tuples.

However, you really shouldn't have to write those types yourself, we should give them to you. Hence the NuGet package. 😄 We also want to put them in the core framework (like in mscorlib) but the framework ships slower than the compiler, so we would end up waiting a while for System.ValueTuple to make it into the framework (and ship through Windows Update, etc.). But tuples are done and ready and you should be able to use them now! 😄

So that's why the System.ValueTuple package exists. I hope that helps!

[MichaelPuckett2]

That does help and I appreciate the clarification. I was wrapped up in other discussions and somewhere in the mix my thinking was thrown off course. Thanks.

[TheManii]

I'm by no means an experienced programmer, but this is my issue with the current c# and net doc deficiencies: many recent language features and constructs don't have their minimum clr and library requirements clearly listed, and in the case of valuetuple, blends library and c# language together.

---

Library requirement issues:

The System.ValueTuple nuget package/library states it will run on net 4.5+/net standard 1.0+, and implies thus that it will work on clr4+ from that. Comments from stack overflow seems to imply that the library will actually run on net 2.0. If that is the case, is it unsupported on net <4.5/net standard <1.0?

The issue here is that the ms docs are inconsistent as far as listing library requirements.

Example point:

• 1: https://docs.microsoft.com/en-us/dotnet/api/system.io.binaryreader?view=netframework-4.7
• 2: https://msdn.microsoft.com/en-us/library/system.io.binaryreader(v=vs.110).aspx
• 3: https://developer.android.com/reference/java/io/FileInputStream.html

The first has no requirement info at all, the second has it at the library/namespace level, the third has it per function. Net libraries seem to add functions to existing library/namespaces infrequently compared to android libraries, but it's very clear in the third example, where you can/cannot use something. In the first link, I can select between net 4.5 though net 4.7 notes, though the reality is shown in the second link: it works all the way back to net 1.1.

The CLR requirements in this example are pretty clear, there are no special language constructs required to use binaryreader, and the api itself is available back to net 1.1: it should run pretty much anywhere.

---

Syntax requirement issues:

The issue here is that C# language features do not clearly state their underlying clr requirements.

Example point:

• : https://www.hanselman.com/blog/HowDoExtensionMethodsWorkAndWhyWasANewCLRNotRequired.aspx

Extension methods introduce a new language concept as part of C#3, but it does not require clr changes to work, it's purely something for the compiler to handle. There's no api/library requirements specific to extension methods, it's purely a language concept.

Is the same true for valuetuple?
Stackoverflow comments suggest that the c#7 valuetuple syntax itself can be compiled down to clr2 with the existing compiler.

The valuetuple docs don't actually state if clr changes were needed to make the new syntax work, valuetuple does depend on the System.Valuetuple library, which itself depends on net 4.5/net standard 1.0, but what if I substitute it with a library that only depends net 2.0 (and thus otherwise could run on clr2), or if the existing library is confirmed to support net 2.0? existing

---

Finally there's still the issue of interoperability with other hosted clr languages, extension methods and valuetuple constructs cannot be directly translated to powershell, even though ps and c# can use the same runtimes. But that might be too specific here and powershell users are generally fending for themselves.

[agocke]

cc @jaredpar

Mapping out our exact library and runtime dependencies can be quite tricky. I'm not sure what plans we have for documentation here.

As for other hosted CLR languages, I can say we try to move C#, VB, and F# forward in API compatibility for features we expect to see commonly used. Powershell and other CLR languages do not typically get this treatment.

[BillWagner]

My plan for the conceptual / overview document is to explain the relationship between the language, and the requirements for a Standard Library. (The Standard Library requirements are described in Appendix C of the ECMA C# spec. They aren’t published in the Microsoft spec).

The thesis of that topic is this:

The C# language requires a standard library to have certain types, and certain accessible members on those types. Examples from the first version of C# include ‘System.Exception’, ‘System.String’ and others. Each new version of the language may add new features that require new types or members in the Standard Library. Version 5 required System.Threading.Tasks.Task and other related types for async and await support. Version 7 requires the System.ValueTuple<> generic types for the new tuple syntax.

In order to decouple the release of a new version of the language from the release of a new standard library, NuGet packages will be used to enable the new language features to be used with older versions of the standard library. Examples of this include NuGet packages for System.Threading.Task and related types, and System.ValueTuple and related types.

The rest of the topic will highlight how this separation enables developers to use the new language features even when they are targeting machines that may not have the corresponding framework. I’ll also add a discussion about the height of the bar for new library requirements in the language definition.

I also want to update the “What’s New” topic to include what Framework version has the required library types, and what NuGet package to use when it doesn’t. I think I’ll only go back as far as version 5 for this content.