Standard
Introduction
The .NET Standard is a formal specification of .NET APIs that are intended to be available on all .NET runtimes. The motivation behind the .NET Standard is establishing greater uniformity in the .NET ecosystem. ECMA
335 continues to establish uniformity for .NET runtime behavior, but there is no similar spec for the .NET Base Class Libraries (BCL) for .NET library implementations.
The .NET Standard enables the following key scenarios:
- Defines uniform set of base class library (BCL) APIs for all .NET platforms to implement, independent of workload.
- Enables developers to produce portable libraries that are usable across .NET runtimes, using this same set of APIs.
- Reduces and hopefully eliminates conditional compilation of shared source due to .NET APIs, only for OS APIs.1
The various .NET runtimes implement specific versions of .NET Standard. Each .NET runtime version advertises the highest .NET Standard version it supports, a statement that means it also supports previous versions. For example, the .NET Framework 4.6 implements .NET Standard 1.3, which means that it exposes all APIs defined in .NET Standard versions 1.0 through 1.3. Similarly, the .NET Framework 4.6.1 implements .NET Standard 1.5, while .NET Core 1.0 implements .NET Standard 1.6.
.NET platforms support
The following table lists all versions of .NET Standard and the platforms supported:
| .NET Standard |
1.0 |
1.1 |
1.2 |
1.3 |
1.4 |
1.5 |
1.6 |
2.0 |
| .NET Core |
1.0 |
1.0 |
1.0 |
1.0 |
1.0 |
1.0 |
1.0 |
2.0 |
| .NET Framework (with tooling 1.0) |
4.5 |
4.5 |
4.5.1 |
4.6 |
4.6.1 |
4.6.2 |
|
|
| .NET Framework (with tooling 2.0 preview) |
4.5 |
4.5 |
4.5.1 |
4.6 |
4.6.1 |
4.6.1 |
4.6.1 |
4.6.1 |
| Mono |
4.6 |
4.6 |
4.6 |
4.6 |
4.6 |
4.6 |
4.6 |
vNext |
| Xamarin.iOS |
10.0 |
10.0 |
10.0 |
10.0 |
10.0 |
10.0 |
10.0 |
vNext |
| Xamarin.Android |
7.0 |
7.0 |
7.0 |
7.0 |
7.0 |
7.0 |
7.0 |
vNext |
| Universal Windows Platform |
10.0 |
10.0 |
10.0 |
10.0 |
10.0 |
vNext |
vNext |
vNext |
| Windows |
8.0 |
8.0 |
8.1 |
|
|
|
|
|
| Windows Phone |
8.1 |
8.1 |
8.1 |
|
|
|
|
|
| Windows Phone Silverlight |
8.0 |
|
|
|
|
|
|
|
- The columns represent .NET Standard versions. Each header cell is a link to a document that shows which APIs got added in that version of .NET Standard.
- The rows represent the different .NET platforms.
- The version number in each cell indicates the minimum version of the platform you'll need to implement that .NET Standard version.
To find the highest version of .NET Standard that you can target, do the following:
- Find the row that indicate the .NET platform you want to run on.
- Find the column in that row that indicates your version starting from right to left.
- The column header indicates the .NET Standard version that your target supports (and any lower .NET Standard versions will also support it).
- Repeat this process for each platform you want to target. If you have more than one target platform, you should pick the smaller version among them. For example, if you want to run on .NET Framework 4.5 and .NET Core 1.0, the highest .NET Standard version you can use is .NET Standard 1.1.
Which .NET Standard version to target
When choosing a .NET Standard version, you should consider this trade-off:
- The higher the version, the more APIs are available to you.
- The lower the version, the more platforms implement it.
In general, we recommend you to target the lowest version of .NET Standard possible. So, after you find the highest .NET Standard version you can target, follow these steps:
- Target the next lower version of .NET Standard and build your project.
- If your project builds successfully, repeat step 1. Otherwise, retarget to the next higher version and that's the version you should use.
.NET Standard versioning rules
There are two primary versioning rules:
- Additive: .NET Standard versions are logically concentric circles: higher versions incorporate all APIs from previous versions. There are no breaking changes between versions.
- Immutable: Once shipped, .NET Standard versions are frozen. New APIs will first become available in specific .NET platforms, such as .NET Core. If the .NET Standard review board believes the new APIs should be made available everywhere, they'll be added in a new .NET Standard version.