expand rid graph examples

docs/core/compatibility/sdk/8.0/rid-graph.md

@@ -1,7 +1,7 @@
 ---
 title: "Breaking change: .NET SDK uses a smaller RID graph"
 description: Learn about a breaking change in the .NET 8 SDK where the SDK uses a smaller, portable RID graph for projects that target .NET 8 or later.
-ms.date: 09/05/2023
+ms.date: 04/01/2024
 ---
 # .NET SDK uses a smaller RID graph
 
@@ -13,7 +13,9 @@ The .NET SDK used a complex [RID graph](../../../rid-catalog.md) to determine as
 
 ## New behavior
 
-Starting in .NET 8, the .NET SDK uses a smaller graph consisting of only portable RIDs, for projects that target .NET 8 or a later version. This means that the SDK won't recognize version-specific or distro-specific RIDs by default.
+Starting in .NET 8, the .NET SDK uses a smaller graph consisting of only portable RIDs, for projects that target .NET 8 or a later version. This means that the SDK won't recognize version-specific or distro-specific RIDs by default. You might see the following error (or similar) when you build your project:
+
+> error NETSDK1083: The specified RuntimeIdentifier 'win10-x64' is not recognized. See <https://aka.ms/netsdk1083> for more information.
 
 ## Version introduced
 
@@ -29,11 +31,29 @@ The RID graph was costly to maintain and understand, requiring .NET itself to be
 
 ## Recommended action
 
-Use portable RIDs, for example, `linux-<arch>`, `linux-musl-<arch>`, `osx-<arch>`, and `win-<arch>`.
+Use portable RIDs, for example, `linux-<arch>`, `linux-musl-<arch>`, `osx-<arch>`, and `win-<arch>`, instead of version-specific or distro-specific RIDs, such as `ubuntu.16.04-<arch>`, `osx.10.11-<arch>`, and `win10-<arch>`.
+
+If you specify the RID by using the [RuntimeIdentifier](../../../project-sdk/msbuild-props.md#runtimeidentifier) MSBuild property in your project file (\*.csproj, \*.vbproj, or \*.fsproj), change it accordingly. For example, change `<RuntimeIdentifier>win10-x64</RuntimeIdentifier>` to `<RuntimeIdentifier>win-x64</RuntimeIdentifier>` in your project file:
+
+```xml
+<PropertyGroup>
+  ...
+  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
+</PropertyGroup>
+```
+
+If you specify the RID as a command-line argument, make a similar change. For example, instead of `dotnet publish --framework net8.0 --runtime win10-x64`, use the command `dotnet publish --framework net8.0 --runtime win-x64`.
 
 If you need to revert to the previous behavior of using the old, full RID graph, you can set the `UseRidGraph` MSBuild property to `true` in your project file. However, the old RID graph won't be updated in the future to attempt to handle any other distros or architectures.
 
+```xml
+<PropertyGroup>
+  <UseRidGraph>true</UseRidGraph>
+</PropertyGroup>
+```
+
 ## See also
 
+- [NETSDK1083: The specified RuntimeIdentifier is not recognized](../../../tools/sdk-errors/netsdk1083.md)
 - [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)

docs/core/tools/sdk-errors/netsdk1083.md

@@ -2,7 +2,7 @@
 title: "NETSDK1083: The specified RuntimeIdentifier is not recognized"
 description: Learn about .NET SDK error NETSDK1083, which warns about an unknown runtime identifier.
 ms.topic: error-reference
-ms.date: 09/19/2023
+ms.date: 04/01/2024
 f1_keywords:
 - NETSDK1083
 ---
@@ -12,4 +12,10 @@ NETSDK1083 warns you that the [runtime identifier](../../rid-catalog.md) (RID) s
 
 To resolve this error, specify a known RID as your project's `RuntimeIdentifier`.
 
-In .NET 8 and later versions, the default behavior of the .NET SDK is to [use a smaller portable RID graph](../../compatibility/sdk/8.0/rid-graph.md). If your project uses a version-specific or distro-specific RID, switch to a portable RID. If you need to revert to the previous behavior of using the old, full RID graph, you can set the `UseRidGraph` MSBuild property to `true` in your project file. The old RID graph is no longer updated and exists only for backwards compatibility, and the option to use it might be removed in a future release.
+In .NET 8 and later versions, the default behavior of the .NET SDK is to [use a smaller portable RID graph](../../compatibility/sdk/8.0/rid-graph.md). If your project uses a version-specific or distro-specific RID, switch to a portable RID. For example, if your project file contains the property `<RuntimeIdentifier>win10-x64</RuntimeIdentifier>`, change it to `<RuntimeIdentifier>win-x64</RuntimeIdentifier>`.
+
+If you need to revert to the previous behavior of using the old, full RID graph, you can set the `UseRidGraph` MSBuild property to `true` in your project file. The old RID graph is no longer updated and exists only for backwards compatibility, and the option to use it might be removed in a future release.
+
+## See also
+
+- [.NET SDK uses a smaller RID graph](../../compatibility/sdk/8.0/rid-graph.md)