.NET Standard - What You Need To Know

What is .NET Standard?

.NET Standard is just that: a standard. It's a document that has been prepared and actively maintained by the .NET Foundation, who oversee development on a large range of the projects either directly related to the .NET stack or which use the .NET platform. Projects like:

.NET Standard lists all of the APIs that each platform with the .NET stack must implement for it to be part of the .NET stack.

David Fowler has produced this analogy to show that .NET Standard can be thought as a C# interface. Paul Seal has created a further analogy (available here), which compares .NET Standard to the various cable standards used by TV equipment.

How Does .NET Standard Affect The .NET Platforms?

As mentioned earlier, .NET Standard acts as a standard which all of the .NET Platforms must be ratified against in order for them to be part of the .NET stack. This means that .NET Standard sets the bar for which APIs are available for each .NET Platform. The standard (like any other standard, for instance the Wireless LAN or ECMA Script standards) has version numbers - a higher version number indicates that more of the API surface has been described and will be required by platforms which implement that version of the standard.

In the official documentation for the .NET Standard Library (which I'd recommend that you take some time to read through), the authors use the following image to show how the different platforms map to the .NET Standard:

.NET Standard Support Table
The .NET Platforms and which version of the .NET Standard they support (click to enlarge)

The top row of the table shows the different versions of .NET Standard, and each subsequent row shows how the versions of each .NET Platforms line up against the .NET Standard.

The arrows indicate that the platform supports a higher version of .NET Standard. For instance, .NET Core 1.0 supports the .NET Standard version 1.6, which is why there are arrows pointing to the right for the lower versions 1.0 – 1.5.

The above quote is taken from: https://blogs.msdn.microsoft.com/dotnet/2016/09/26/introducing-net-standard/

The .NET Standard compatibility image (above) mentions .NET Standard 2.0, but (at the time or writing) this has not yet been released. In the image we can see that .NET Framework 4.6.1 is already ratified against version 2.0 of the standard, this is because .NET Framework 4.6.1 was used as the baseline for .NET Standard 2.0.

Once .NET Standard 2.0 is released .NET Core, Xamarin, Mono, and the Universal Windows Platform will all have the same API surface as .NET Framework 4.6.1. As a visual example of the API surface that will be available, here is a table showing the number of APIs for each version of the .NET Standard:

.NET Standard API Count by Version Number
Table showing each version of the .NET Standard and the API counts for them

Which .NET Platform Should I Choose?

That is entirely up to the needs of the project.

Until .NET Standard 2.0 is released, if your project requires access to the full suite of .NET APIs, then targeting .NET Framework 4.6.1 would probably be the best option. This would obviously leave you without access to Kestrel (.NET Core's web server) and cross platform options (the ability to run an instance of the project on servers running either MacOS or Linux, for instance).

Once version 2.0 of .NET Standard has been released, the choice will be:

Is your project required to be cross platform, and does the time required to learn .NET Core outweigh the benefit of your project being cross platform?

There are more detailed things to take into consideration, but this would be one of the first questions for a new .NET project, once version 2.0 of .NET Standard is released. This is because .NET Core (and by extension Kestrel) has it's own way of doing certain things, which are a little different to how .NET Framework does things - which could easily catch some people out.

Where Can I See Which APIs Are Available?

The best place that you can check is https://apisof.net/. This is a webapp which is built and maintained by the team behind .NET Standard and allows you to browse or search for an AP by name and it will list the versions of each platform that support it.

Searching for String.IsNullOrWhiteSpace on apisof.net will give a result similar to this:

aspisof String.IsNullOrEmpty (cropped)
Showing the page for String.IsNullOrWhiteSpace from apisof.net (image has been cropped to remove unnecessary detail, click to enlarge)

If you want to know how easily a pre-existing .NET Framework solution will port to .NET Core, then you can upload its packages.config, project.json or packet.dependencies files to https://icanhasdot.net/. This is a tool built and maintained by OctopusDeploy, it requires you to either upload files from your solution (which might be under NDA) or link to an existing GitHub repository.

Here is a cropped screenshot of the result of running one of my personal projects through this tool:

icanhasdotnet - example
This is cropped to the first 30 supported packages. The actual report is much longer (click to enlarge)

.NET Standard Resources

Immo Landwerth is the go-to guy for all things .NET Standard. He is one of the Program Managers for .NET Core and the loudest promoter of the .NET Standard.

As mentioned earlier, it is entirely worth reading through the documentation for the .NET Standard, which is available here.