[Breaking Change] Improving .NET Core Version APIs

[richlander]

[Breaking Change] Improving .NET Core Version APIs

We are improving the .NET Core version APIs in .NET Core 3.0. The particular changes we made are technically breaking. The changes are currently only in the master branch, so will be part of .NET Core 3.0 Preview 4, modulo feedback.

Also posted at dotnet/coreclr dotnet/runtime#23011

Related:

• Improve .NET Core version APIs dotnet/corefx dotnet/runtime#28701
• Make Environment.Version return the actual runtime version dotnet/corefx dotnet/runtime#26833
• Use product version in RuntimeInformation.FrameworkDescription dotnet/corefx dotnet/corefx#35516
• Change Environment.Version to return product version dotnet/coreclr dotnet/corefx#22664

Goal

The goal of the improvement is to enable access to accurate and precise product version information, like is displayed in the following example:

C:\testapps\versioninfo>dotnet run
.NET Core version:
Environment.Version: 3.0.0
RuntimeInformation.FrameworkDescription: .NET Core 3.0.0-preview4.19113.15
CoreFX Build: 3.0.0-preview4.19113.15
CoreFX Hash: add4cacbfb7f7d3f5f07630d10b24e38da4ad027

Code: https://gist.github.com/richlander/f5849c6967c66d699301f75101906f99

Existing Behavior

The product (as of .NET Core 3.0 Preview 3) does not provide the version information displayed above, but seemingly arbitrary values, as displayed in the following example (using the same code):

C:\testapps\versioninfo>dotnet run
.NET Core version:
Environment.Version: 4.0.30319.42000
RuntimeInformation.FrameworkDescription: .NET Core 4.6.27415.71
CoreFX Build: 4.7.0-preview4.19113.15
CoreFX Hash: add4cac

Note: These version strings are based on the .NET Framework heritage of the product.

Breaking Change

The change is technically breaking because it resets the versioning scheme of the product as reported by these APIs. Some code somewhere will break, however, we do not expect that to be pervasive. Unfortunately, it will be hard to write code that works with both the new behavior and old behavior given how close the values are.

We should never have shipped .NET Core 1.0 with this behavior to avoid this problem now. We decided that .NET Core 3.0 is likely our last chance to fix these APIs, so decided to take the opportunity now.

Feedback

We would love your feedback.

[EdiWang]

This is great! I have struggled with getting .NET Core version for a long time.

BTW, could we have a label "Breaking Change" to help track these issues? It would be helpful after .NET Core 3.0 release and we can see what could break when retargeting 2.x code to 3.0.

[richlander]

I added the label for you. Good idea.

I am closing this issue now. The change is in .NET Core 3.0 Preview 4.

[karelz]

I don't think this label is that useful, unless we have process to use it. I recommend to keep an MD file with list of breaking changes, given that we have so few.
Deleting the label, to keep some sanity in number of labels we have (which is already way too high :()