What are the .NET Standard versioning rules?

Question

.NET Standard prescribes an API that all .NET Platforms must implement. What are its versioning rules? Is it breaking.adding, in which 1.4 adds to and remains backward compatible with 1.3 whereas 2.x is not backward compatible with 1.x?

The documentation is not clear on this. Some Microsoft docs indicate pure backward compatibility:

Given a .NET Standard Library version, you can use libraries that target that same or lower version. (emphasis added)

Now that 2.0 is out, the above doesn't seem correct. That being said, the release blog post said:

From a library targeting .NET Standard you’ll be able to reference [libraries targeting] .NET Standard, if their version is lower or equal to the version you’re targeting. (emphasis added)

That same blog post contradicted itself by saying:

In order to allow .NET Framework 4.6.1 to support .NET Standard 2.0, we had to remove all the APIs from .NET Standard that were introduced in .NET Standard 1.5 and 1.6.

Now that 2.0 is out, what are the versioning rules? It appears to be breaking.adding. Where has MSFT documented this?

Answer 1

I've explained this in a bit more detail in our On.NET episode on .NET Standard.

Generally, this is how .NET Standard works:

1. .NET Standard will version linearly, with the intention of not making breaking changes between versions. In other words, you can think of the API surface of .NET Standard as concentric circles, where higher versions have more APIs.
2. A specific version of a .NET platform will implement a specific version of .NET Standard.
3. When choosing a .NET Standard version to target consider this trade-off:
   • The higher the version number, the more APIs you can use
   • The lower the version number, the more .NET platforms support it

So why is there this talk about breaking changes? The short answer is because we made a mistake when defining .NET Standard 1.x and didn't take platform reach into consideration. You should ignore .NET Standard 1.5 and 1.6 and avoid taking a dependency on them. If you do that, .NET Standard 2.0 is a strict superset of .NET Standard 1.4.

For more details, read the section .NET Standard 2.0 breaking change: adding .NET Framework 4.6.1 compatibility in my blog post on .NET Standard.

Update. After a lot of community feedback we decided not to perform this breaking change. More details around this decision is listed in the .NET Standard FAQ.