Today, some of my colleagues had a discussion about .NET Standard. Is it a new framework, an extension to classic .NET framework, or to .NET core? Confusion was great and in today’s post, I would like to shed light on the matter.
What is .NET Standard?
.NET Standard is a specification which defines a set of APIs which the .NET platform has to implement. It is not another .NET platform though. You can only build libraries, not executables with it. On the following screenshot, you can see that .NET Standard contains APIs from the classic .NET framework, .NET core and Xamarin.
What is .NET Standard (Source)
The following screenshot shows that it defines a set all APIs that all .NET frameworks implement.
Implementation of .NET Standard (Source)
The difference to Portable Class Libraries
Some of you might remember portable class libraries, which sound like .NET Standard. Both technologies have the same idea but a portable class library needs to be recompiled every time you want to use it for a different target. .NET Standard doesn’t have to be recompiled to be used for a different target. Check out the following screenshot to compare the differences:
Portable Class Library vs .NET Standard (Source)
Portable class libraries are deprecated because .NET Standard is better in every way and therefore shouldn’t be used anymore.
Choosing the right Version
A new version of .NET Standard always contains all previous APIs and additional ones. The following screenshot shows how a new version is built on all previous ones:
Every version is built on the previous one (Source)
A .NET platform implements a specific .NET Standard version, for example .NET Core 1.0 implements .NET Standard 1.6. The enforce this backward compatibility, every .NET Standard version is immutable.
Which Version to choose?
The best practice is to start with a high version number and implement all your features. Then target the lowest version possible. For example, start with 2.0 and then decrease to 1.6, then 1.5 until your project doesn’t compile anymore.
Find out which Version a .NET Platform implements
Microsoft has some great documentation about which .NET Standard version is implemented by which .NET framework version.
If you are looking for a specific API, you can go to https://docs.microsoft.com/en-gb/dotnet/api/ and search for it.
Version 1.6 has around 13,000 APIs whereas version 2.0 has already around 32,000 APIs which includes for example Primitives, Collections, Linq or Files
Some APIs of 2.0 (Source)
Migrating an existing project
Migrating to .NET Standard just for the sake of migrating is not the best strategy. It makes sense to migrate if the heart of your library is .NET Standard compatible and if you want to use it on different .NET platform.
How to migrate
Open the .csproj file of the classic .NET framework project you want to migrate and delete everything. Then copy a new Project tag with the target framework of netstandard in it. If you want to migrate a .NET core project, you only have to change the target framework to netstandard. For details see the following screenshot:
If you are migrating a .NET core project, you are already done. For your .NET framework project, you have to delete the AssemblyInfo.cs and the packages.config files. Then you have to reinstall your NuGet packages. The reason why you don’t have to do that for .NET core is because it uses package referencing and not the packages.config.
Targeting multiple platforms
If you want to target multiple frameworks, for example, .NET Standard and .NET 4.6.1, you only have to change the TargetFramework tag in the .csproj file to TargetFrameworks and separate the different framework with a semicolon.
If you use multiple target platforms, you can use if statements to use different code, depending on your target framework:
In this short post, I explained the basics of .NET Standard and pointed out why it is better than the deprecated portable class library. Additionally, I showed how to migrate your existing project and how to target multiple platforms. For more information, I can highly recommend the Pluralsight course “.NET Standard: Getting Started” by Thomas Claudius Huber.