.NET Standard Explained: How to Share Code
.NET Standard Explained: How to Share Code
How exactly do the various .NET runtimes manage to share and run code between themselves? We take a look into how this is accomplished in the .NET ecosystem.
Join the DZone community and get the full member experience.Join For Free
The new Gartner Critical Capabilities report explains how APIs and microservices enable digital leaders to deliver better B2B, open banking and mobile projects.
You can learn how the .NET ecosystem works on Stackify. It consists of runtimes (.NET Framework, .NET Core, and Mono for Xamarin), class libraries, and a common infrastructure (runtime tools and languages).
In this article, we are going to talk about the thing that makes the runtimes play well together and enables them to share code. Here, you’ll learn what .NET Standard is and what it isn’t.
The .NET Framework contains the .NET Framework Class Library. This contains all the basic classes like Collections, strings, but also classes to connect with data sources, work asynchronously, and so on.
.NET Core also has a class library. This one is a subset of the .NET Framework library and contains less APIs.
And the Xamarin application workloads that run on the Mono runtime also have a class library, which is also a subset of the .NET Framework class library, more geared towards the purpose of the Xamarin application workloads.
Having different class libraries with different sets of APIs is not very useful. This makes it difficult to share code between runtimes as the code you write for one runtime might not work in another runtime because it doesn’t have the APIs that you need.
To solve the difficulties with having multiple class libraries, there is .NET Standard. This is a set of specifications that tell you which APIs you can use. This specification is implemented by all the runtimes.
.NET Standard is not something that you install – it is a formal specification of APIs that you can use. .NET Standard is an evolution of Portable Class Libraries. Portable Class Libraries are another way of sharing code between projects.
Runtimes, like .NET Core, implement .NET Standard. Specific runtime versions implement specific versions of .NET Standard, thereby implementing a specific set of APIs. For instance, the .NET Framework 4.5 implements .NET Standard 1.1 and with that, all the .NET Standard versions that came before 1.1.
The purpose of .NET Standard is simple: to share code between runtimes. When you want to share code between different runtimes in the .NET Ecosystem, use .NET Standard.
Portable Class Libraries
A word about Portable Class Libraries, or PCLs. A Portable Class Library is just what it sounds like, a class library that is portable. It is a class library that you write and can use in applications that run on multiple platforms. Their purpose is to share code between applications, just like .NET Standard does.
.NET Standard is the evolution of PCLs and will eventually replace PCLs completely. Here are the main differences between .NET Standard and PCLs:
- .NET Standard is a set of curated APIs, picked by Microsoft, which PCLS are not.
- The APIs that a PCL contains are dependent on the platforms that you choose to target when you create a PCL. This makes a PCL only shareable for the specific targets that you choose.
- .NET Standard is platform-agnostic, it can run anywhere, on Windows, Mac, Linux, and so on.
- PCLs can also run cross-platform, but they have a more limited reach. PCLs can only target a limited set of platforms.
.NET Standard Versioning
Alright, let’s talk a bit about how .NET Standard is versioned.
Each version of .NET Standard contains a certain set of APIs, like System.Collections and System.IO. Each new version of .NET Standard contains all the APIs of the previous versions and some new ones. This makes .NET Standard backward compatible.
So each version contains all of the APIs of the previous versions. There are no breaking changes between versions and when a version is generally available, its contents will never change, so you can rely on the API specification of that version.
Specific runtime versions implement specific .NET Standard versions.
Each version contains an amount of APIs. Each higher version contains more APIs. This keeps on growing with each version. Higher version numbers of .NET Standard mean that they contain more APIs. But lower versions are supported by more platforms.
So, therefore, if you create a .NET Standard library that you want to share, you should always target the lowest version of .NET Standard that you can get away with. This way, you can reach the maximum amount of platforms.
Higher version = more APIs.
Lower version = more platforms.
Target the lowest version that you can.
.NET Standard Tools
There are several tools that can help you to get started with .NET Standard.
.NET API Browser
You can use the .NET API Browser to find out what APIs are in which version of .NET Standard. This is a great page on the Microsoft docs website. Just select the .NET Standard version that you want to browse and either browse or search for specific functionality. This is a really good tool.
.NET Portability Analyzer
You can also analyze your current projects for compatibility with a specific .NET Standard version to see if you can convert them to .NET Standard. To do this, you can use the .NET Portability Analyzer, which is a tool from the Visual Studio Marketplace. You can use it from Visual Studio or from the command line.
Finally, I wanted to address Shared projects. You see these things in Visual Studio and they look like another form of code sharing, next to PCLs and .NET Standard.
So what are they? Shared Projects are a project template in Visual Studio that do not result in assemblies when you build them. They are just links between files and projects, just like linked files did in previous versions of Visual Studio. They do not provide any APIs like PCLs and .NET Standard do, they just act as a file-sharing mechanism between projects.
Look at the example in the image above. The ConsoleApp project references the ShareProject1 project, which contains the SharedClass class.
When you build this, from the compilers’ viewpoint, the ConsoleApp contains the SharedClass class and the SharedProject doesn’t exist.
Shared Projects are nothing more than a Tool in Visual Studio that helps you to share files. They aren’t bad things, they are just different than .NET Standard and they are Visual Studio specific.
So, we’ve learned that .NET Standard is not a physical thing, but a specification of APIs.
It is the next version of Portable Class Libraries and it can be used by all the runtimes in the .NET ecosystem (.NET Framework, .NET Core, and Mono for Xamarin). Each runtime implements .NET Standard.
It has an additive versioning system, meaning that each new version contains all the APIs of the previous versions, which makes it backward compatible. And there never are any breaking changes between versions.
Let me know what you think in the comments.
Published at DZone with permission of Barry Luijbregts , DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.