Target .NET standard when building a shared project or library in .NET

In this post, I outline some bits I have learned about .NET standard.

What is .NET Standard?

.NET standard is a contract which defines the set of APIs (namespaces, classes and methods) you can use for working with file system, networking, threading, etc … I think of it as similar to an interface, but at a much larger scale. As the name suggests, .NET standard defines the APIs, but it does not contain implementations. The actual frameworks that implement .NET Standard include .NET framework, .NET core, Mono, and Xamarin.

.NET Standard is a specification of .NET APIs that are available on all .NET implementations. Targeting .NET Standard lets you produce libraries that are constrained to use APIs that are in a given version of .NET Standard, which means it’s usable by all platforms that implement that version of the .NET Standard.

Cross-Platform Targeting

Why .NET Standard?

.NET framework has been around for a long time, and it has powered billions of systems. The full .NET framework only runs on Windows and contains a heavy set of libraries, many of which you may not need in a project. .NET Core is like a cool kid in town. It is cross-platform, lightweight and more performant compared to the full .NET framework. However, .NET Core does not contain all the libraries that exist in .NET framework, especially the ones that requires Windows. While Microsoft is putting more emphasis and support on .NET Core, .NET Framework is here to stay because too many things depend on it. What does it mean for us as developers? If you want to build a library and want it to be usable by different projects that target different .NET frameworks, you need to target a version of .NET Standard which all the frameworks you want to support implement. For instance, If you library targets just a version of the full .NET framework, it is not going to be usable by a project that targets .NET Core because your library could use APIs that are not available in .NET Core and vice versa.

Which version of .NET Standard?

The lowest version of .NET Standard is 1.0 and the latest version, as of this writing is 2.1, which is still in preview. Each implementation of .NET Standard implements a specific version of it and all the versions below it. For instance, .NET core 2.0 implements .NET Standard 2.0, which means it implements .NET Standard versions from 1.0 up to and including 2.0 (1.0, 1.1, …1.6, 2.0). The lower the version of .NET Standard you target, the less APIs you have available to you, and the broader .NET applications can consume your library.

The table below helps to determine which version of .NET Standard you should target. It is from the documentation.

.NET Standard	1.0	1.1	1.2	1.3	1.4	1.5	1.6	2.0	2.1 Preview
.NET Core	1.0	1.0	1.0	1.0	1.0	1.0	1.0	2.0	3.0
.NET Framework 1	4.5	4.5	4.5.1	4.6	4.6.1	4.6.1 2	4.6.1 2	4.6.1 2	N/A3
Mono	4.6	4.6	4.6	4.6	4.6	4.6	4.6	5.4	6.4
Xamarin.iOS	10.0	10.0	10.0	10.0	10.0	10.0	10.0	10.14	12.16
Xamarin.Mac	3.0	3.0	3.0	3.0	3.0	3.0	3.0	3.8	5.16
Xamarin.Android	7.0	7.0	7.0	7.0	7.0	7.0	7.0	8.0	10.0
Universal Windows Platform	10.0	10.0	10.0	10.0	10.0	10.0.16299	10.0.16299	10.0.16299	TBD
Unity	2018.1	2018.1	2018.1	2018.1	2018.1	2018.1	2018.1	2018.1	TBD

The following steps show how to use the table to select a version of .NET Standard for your project:

1. Go down and then across all the way until you hit the version immediately higher than the one you want to support, or you reach the end.
2. If you hit the version higher than the one you want to support, then back up one column.
3. From the .NET framework version, get the corresponding .NET Standard version in the first row of the same column.
4. Repeat the above steps for each of the .NET framework which you want your library to support.
5. If you get multiple versions of .NET Standard, pick the lowest version as that would ensure your library is usable when running under all the versions of the .NET framework you want to support.

For example, suppose you build a library and want to make available to two other projects that target .NET Core 1.0 and .NET framework 4.5.1 respectively. Looking at the table, you see the highest .NET Standard version which .NET Core 1.0 implements is 1.6. However, the highest .NET Standard version which .NET framework 4.5.1 implements is 1.2. Therefore, you should target .NET Standard 1.2 if you want your library to be usable by both the two projects.

Other tips to help with selecting an appropriate .NET Standard version:

• If you are not sure which version of .NET Standard you should target, go with 2.0 as it offers a balance of reach and APIs available for you to use.
• If your goal is to make your library usable for many frameworks as possible while gettings all the APIs you can from .NET Standard, you can target the highest version of .NET Standard, and then gradually decrease the version until your project no longer compile.
• .NET framework 4.6.1 has some issues with .NET Standard 2.0. If your library target .NET Standard 2.0 and you want to support 4.6.1, consider upgrading to .NET framework 4.7.2 or higher. You can also use multi-targeting to target both .NET Standard 2.0 and .NET framework 4.6.1.

Helpful Urls

These urls are from the video on “Build great libraries using .NET Standard”. The video contains great info and tips for working with .NET Standard and targeting multiple frameworks. You can find the link in the References section.

• https://apisof.net/: You can search for an API and see if it exists in one or more .NET frameworks.

• https://source.dot.net: See the source codes of .NET core libraries.

• https://referencesource.microsoft.com: See the source code of .NET framework libraries.

References

.NET Standard.

Can a .NET Core Web app consume .NET Framework class libraries?

.NET architectural components

Cross-platform targeting