From cc0da45c7ccea417df7d1202d17dd3389413039c Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 7 Jun 2023 18:33:14 -0700 Subject: [PATCH 1/2] rid assets --- docs/core/compatibility/8.0.md | 1 + .../deployment/8.0/rid-asset-list.md | 70 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 ++ 3 files changed, 75 insertions(+) create mode 100644 docs/core/compatibility/deployment/8.0/rid-asset-list.md diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index 17aa6716d9e68..02c5467c6e4f9 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -49,6 +49,7 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff | Title | Type of change | Introduced | | ----------------------------------------------------------------------- | ----------------- | ---------- | +| [Host determines RID-specific assets](deployment/8.0/rid-asset-list.md) | Binary incompatible/behavioral change | Preview 5 | | [StripSymbols defaults to true](deployment/8.0/stripsymbols-default.md) | Behavioral change | Preview 4 | ## Entity Framework Core diff --git a/docs/core/compatibility/deployment/8.0/rid-asset-list.md b/docs/core/compatibility/deployment/8.0/rid-asset-list.md new file mode 100644 index 0000000000000..8f99ae5af16c6 --- /dev/null +++ b/docs/core/compatibility/deployment/8.0/rid-asset-list.md @@ -0,0 +1,70 @@ +--- +title: "Breaking change: Host determines RID-specific assets" +description: Learn about the breaking change in deployment in .NET 8 where the runtime host looks for RID-specific assets via a known list. +ms.date: 06/07/2023 +--- +# Host determines RID-specific assets + +When running an application with [RID](../../../rid-catalog.md)-specific assets, the host determines which assets are relevant for the platform on which it's running. This applies to both the application itself and the resolution logic used by . + +Previously, the host tried to compute the RID at run time and then read the RID graph to determine which RID-specific assets matched or were compatible with the computed RID. Now, the default behavior doesn't compute the RID or use the RID graph. Instead, the host relies on a known list of RIDs based on how the runtime itself was built. + +## Previous behavior + +Previously, the process for selecting RID-specific assets was: + +1. Read the RID graph from the *.deps.json* file of the root framework (Microsoft.NetCore.App). +1. Compute the current RID at run time and try to find an entry for it in the RID graph. If it doesn't exist, check for a fallback RID (built into the host at compile time). +1. Starting from the entry found in the RID graph, look for assets matching that RID. +1. Continue down the list of RIDs in the RID graph entry until an asset match is found or the list ends. + +If the RID graph didn't have the computed RID or the fallback RID, RID assets weren't properly resolved. + +## New behavior + +By default, the process no longer relies on the RID graph. Instead, it checks for a known set of portable RIDs based on how the host was built. For example: + +Linux + +- linux-x64 +- linux +- unix-x64 +- unix +- any + +Windows + +- win-x64 +- win +- any + +macOS + +- osx-x64 +- osx +- unix-x64 +- unix + +For non-portable builds of the host/runtime, the build might also set a non-portable RID that is checked first. + +## Version introduced + +.NET 8 Preview 5 + +## Type of breaking change + +This change can affect [binary compatibility](../../categories.md#binary-compatibility) and is also a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The RID graph was costly to maintain and understand, requiring .NET itself to be distro-aware in a fragile manner. The .NET team and the community spend a non-trivial amount of time updating the graph and backporting such updates to previous releases. The long-term goal is to stop updating the RID graph, stop reading it, and eventually remove it. This breaking change is a step towards that goal. + +## Recommended action + +Use portable RIDs, for example, `linux`, `linux-musl`, `osx`, and `win`. For specialized use cases, you can use APIs like or for custom loading logic. + +If you need to revert to the previous behavior, set the backwards compatibility switch `System.Runtime.Loader.UseRidGraph` to `true` in your *runtimeconfig.json* file or as an MSBuild property in your project file. Setting the switch to `true` instructs the host to use the previous behavior of reading the RID graph. + +## Affected APIs + +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index add3081fd27f6..962b76211da16 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -46,6 +46,8 @@ items: href: cryptography/8.0/rsa-encrypt-decrypt-value-obsolete.md - name: Deployment items: + - name: Host determines RID-specific assets + href: deployment/8.0/rid-asset-list.md - name: StripSymbols defaults to true href: deployment/8.0/stripsymbols-default.md - name: Entity Framework Core @@ -1184,6 +1186,8 @@ items: items: - name: .NET 8 items: + - name: Host determines RID-specific assets + href: deployment/8.0/rid-asset-list.md - name: StripSymbols defaults to true href: deployment/8.0/stripsymbols-default.md - name: .NET 7 From 6472f70792f731e145d7de6a2e39b94004f41d61 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 8 Jun 2023 10:25:14 -0700 Subject: [PATCH 2/2] Apply suggestions from code review --- docs/core/compatibility/deployment/8.0/rid-asset-list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/deployment/8.0/rid-asset-list.md b/docs/core/compatibility/deployment/8.0/rid-asset-list.md index 8f99ae5af16c6..6c8737b67ff7a 100644 --- a/docs/core/compatibility/deployment/8.0/rid-asset-list.md +++ b/docs/core/compatibility/deployment/8.0/rid-asset-list.md @@ -45,7 +45,7 @@ macOS - unix-x64 - unix -For non-portable builds of the host/runtime, the build might also set a non-portable RID that is checked first. +For non-portable builds of the host or runtime, the build might also set a non-portable RID that's checked first. ## Version introduced