Core libraries breaking changes for RC 1 (#36992)

gewarren · web-flow · commit 8cfe70fe0e55 · 2023-09-08T08:55:55.000-07:00
diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md
@@ -50,11 +50,13 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 | [FileStream writes when pipe is closed](core-libraries/8.0/filestream-disposed-pipe.md)                   | Behavioral change   | Preview 1    |
 | [GC.GetGeneration might return Int32.MaxValue](core-libraries/8.0/getgeneration-return-value.md)          | Behavioral change   | Preview 4    |
 | [GetFolderPath behavior on Unix](core-libraries/8.0/getfolderpath-unix.md)                                | Behavioral change   | Preview 1    |
+| [GetSystemVersion no longer returns ImageRuntimeVersion](core-libraries/8.0/getsystemversion.md)          | Behavioral change   | RC 1            |
 | [IndexOfAnyValues renamed to SearchValues](core-libraries/8.0/indexofanyvalues-renamed.md)                | Source/binary incompatible | Preview 5 |
 | [ITypeDescriptorContext nullable annotations](core-libraries/8.0/itypedescriptorcontext-props.md)         | Source incompatible | Preview 1    |
 | [Legacy Console.ReadKey removed](core-libraries/8.0/console-readkey-legacy.md)                            | Behavioral change   | Preview 1    |
 | [Method builders generate parameters with HasDefaultValue set to false](core-libraries/8.0/parameterinfo-hasdefaultvalue.md) | Behavioral change   | Preview 5    |
 | [Removed overloads of ToFrozenDictionary/ToFrozenSet](core-libraries/8.0/optimizeforreading-arg.md)       | Source/binary incompatible | Preview 7 |
+| [RuntimeIdentifier returns platform for which runtime was built](core-libraries/8.0/runtimeidentifier.md) | Behavioral change   | RC 1            |
 
 ## Cryptography
 
diff --git a/docs/core/compatibility/core-libraries/8.0/getsystemversion.md b/docs/core/compatibility/core-libraries/8.0/getsystemversion.md
@@ -0,0 +1,47 @@
+---
+title: ".NET 8 breaking change: GetSystemVersion no longer returns ImageRuntimeVersion"
+description: Learn about the .NET 8 breaking change in core .NET libraries where RuntimeEnvironment.GetSystemVersion no longer returns ImageRuntimeVersion, which is a .NET Framework-oriented value.
+ms.date: 09/06/2023
+---
+# GetSystemVersion no longer returns ImageRuntimeVersion
+
+<xref:System.Runtime.InteropServices.RuntimeEnvironment.GetSystemVersion?displayProperty=nameWithType> no longer returns <xref:System.Reflection.Assembly.ImageRuntimeVersion?displayProperty=nameWithType>, which is a .NET Framework-oriented value. It's been updated to return a more relevant value, however, the historical leading `v` has been maintained.
+
+## Previous behavior
+
+<xref:System.Runtime.InteropServices.RuntimeEnvironment.GetSystemVersion?displayProperty=nameWithType> returned <xref:System.Reflection.Assembly.ImageRuntimeVersion?displayProperty=nameWithType>, which is an indicator of .NET Framework in-place replacement, not a product release.
+
+Example: `v4.0.30319`
+
+## New behavior
+
+Starting in .NET 8, <xref:System.Runtime.InteropServices.RuntimeEnvironment.GetSystemVersion?displayProperty=nameWithType> returns `"v"` concatenated with <xref:System.Environment.Version?displayProperty=nameWithType>, which is the version of the CLR.
+
+Example: `v8.0.0`
+
+## Version introduced
+
+.NET 8 RC 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The existing version wasn't useful or meaningful for .NET.
+
+## Recommended action
+
+Update your code to expect the new version, or use `typeof(object).Assembly.ImageRuntimeVersion` instead.
+
+## Affected APIs
+
+- <xref:System.Runtime.InteropServices.RuntimeEnvironment.GetSystemVersion?displayProperty=fullName>
+
+## See also
+
+The following changes are related:
+
+- [Improved .NET Core version APIs](../../../whats-new/dotnet-core-3-0.md#improved-net-core-version-apis)
+- [FrameworkDescription's value is .NET instead of .NET Core](../5.0/frameworkdescription-returns-net-not-net-core.md)
diff --git a/docs/core/compatibility/core-libraries/8.0/runtimeidentifier.md b/docs/core/compatibility/core-libraries/8.0/runtimeidentifier.md
@@ -0,0 +1,41 @@
+---
+title: ".NET 8 breaking change: RuntimeIdentifier returns platform for which the runtime was built"
+description: Learn about the .NET 8 breaking change in core .NET libraries where RuntimeInformation.RuntimeIdentifier returns the platform for which the runtime was built.
+ms.date: 09/06/2023
+---
+# RuntimeIdentifier returns platform for which the runtime was built
+
+<xref:System.Runtime.InteropServices.RuntimeInformation.RuntimeIdentifier?displayProperty=nameWithType> returns the platform for which the runtime was built, rather than a value computed at run time.
+
+## Previous behavior
+
+The value was a runtime identifier (RID) computed via OS files or APIs. This generally meant it was a version-specific and distro-specific RID. For example, when running an application on Windows 11, the value was `win10-x64` or, on Ubuntu 20.04, it could be `ubuntu.20.04-x64`.
+
+## New behavior
+
+Starting in .NET 8, the value is the RID for which the runtime was built. This means that for portable builds of the runtime (all Microsoft-provided builds), the value is non-version-specific and non-distro-specific. For example, the value on Windows 11 is `win-x64`, and on Ubuntu 20.04, it's `linux-x64`. For non-portable builds (source-build), the build sets a build RID that can have a version and distro, and that value is the RID that's returned.
+
+## Version introduced
+
+.NET 8 RC 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change is in line with a .NET 8 change to [RID-specific asset resolution](../../deployment/8.0/rid-asset-list.md) and the move away from a distro-aware runtime. <xref:System.Runtime.InteropServices.RuntimeInformation.RuntimeIdentifier?displayProperty=nameWithType> is an opaque value that should represent the platform on which the host or runtime considers itself to be running. In .NET 8, that corresponds to the platform for which the host or runtime is built, rather than an RID computed at run time.
+
+## Recommended action
+
+<xref:System.Runtime.InteropServices.RuntimeInformation.RuntimeIdentifier?displayProperty=nameWithType> is an opaque value and not intended to be parsed into its component parts. For the OS version of the actual machine an application is running on, use <xref:System.Environment.OSVersion?displayProperty=nameWithType>. For a description, use <xref:System.Runtime.InteropServices.RuntimeInformation.OSDescription?displayProperty=nameWithType>. For a specific ID (distro) and corresponding version on Linux, you can read the [os-release](https://www.freedesktop.org/software/systemd/man/os-release.html) file.
+
+## Affected APIs
+
+- <xref:System.Runtime.InteropServices.RuntimeInformation.RuntimeIdentifier?displayProperty=fullName>
+
+## See also
+
+- [.NET SDK uses a smaller RID graph](../../sdk/8.0/rid-graph.md)
+- [Host determines RID-specific assets](../../deployment/8.0/rid-asset-list.md)
diff --git a/docs/core/compatibility/sdk/8.0/rid-graph.md b/docs/core/compatibility/sdk/8.0/rid-graph.md
@@ -36,3 +36,4 @@ If you need to revert to the previous behavior of using the old, full RID graph,
 ## See also
 
 - [Host determines RID-specific assets](../../deployment/8.0/rid-asset-list.md)
+- [RuntimeIdentifier returns platform for which the runtime was built](../../core-libraries/8.0/runtimeidentifier.md)
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -56,6 +56,8 @@ items:
         href: core-libraries/8.0/getgeneration-return-value.md
       - name: GetFolderPath behavior on Unix
         href: core-libraries/8.0/getfolderpath-unix.md
+      - name: GetSystemVersion no longer returns ImageRuntimeVersion
+        href: core-libraries/8.0/getsystemversion.md
       - name: IndexOfAnyValues renamed to SearchValues
         href: core-libraries/8.0/indexofanyvalues-renamed.md
       - name: ITypeDescriptorContext nullable annotations
@@ -66,6 +68,8 @@ items:
         href: core-libraries/8.0/parameterinfo-hasdefaultvalue.md
       - name: Removed overloads of ToFrozenDictionary/ToFrozenSet
         href: core-libraries/8.0/optimizeforreading-arg.md
+      - name: RuntimeIdentifier returns platform for which runtime was built
+        href: core-libraries/8.0/runtimeidentifier.md
     - name: Cryptography
       items:
       - name: AesGcm authentication tag size on macOS
@@ -1090,6 +1094,8 @@ items:
         href: core-libraries/8.0/getgeneration-return-value.md
       - name: GetFolderPath behavior on Unix
         href: core-libraries/8.0/getfolderpath-unix.md
+      - name: GetSystemVersion no longer returns ImageRuntimeVersion
+        href: core-libraries/8.0/getsystemversion.md
       - name: IndexOfAnyValues renamed to SearchValues
         href: core-libraries/8.0/indexofanyvalues-renamed.md
       - name: ITypeDescriptorContext nullable annotations
@@ -1100,6 +1106,8 @@ items:
         href: core-libraries/8.0/parameterinfo-hasdefaultvalue.md
       - name: Removed overloads of ToFrozenDictionary/ToFrozenSet
         href: core-libraries/8.0/optimizeforreading-arg.md
+      - name: RuntimeIdentifier returns platform for which runtime was built
+        href: core-libraries/8.0/runtimeidentifier.md
     - name: .NET 7
       items:
       - name: API obsoletions with default diagnostic ID

Original file line number	Diff line number	Diff line change
`@@ -36,3 +36,4 @@ If you need to revert to the previous behavior of using the old, full RID graph,`
`36`	`36`	`## See also`
`37`	`37`
`38`	`38`	`- [Host determines RID-specific assets](../../deployment/8.0/rid-asset-list.md)`
	`39`	`+- [RuntimeIdentifier returns platform for which the runtime was built](../../core-libraries/8.0/runtimeidentifier.md)`