dotnet · gewarren · Sep 6, 2023 · Sep 5, 2023 · Sep 5, 2023 · Sep 5, 2023
@@ -82,12 +82,12 @@
         {
             "source_path_from_root": "/docs/core/compatibility/core-libraries/7.0/binaryformatter-apis-produce-errors.md",
             "redirect_url": "/dotnet/core/compatibility/serialization/7.0/binaryformatter-apis-produce-errors",
-            "redirect_document_id": true    
+            "redirect_document_id": true
         },
         {
             "source_path_from_root": "/docs/core/compatibility/core-libraries/7.0/serializationformat-binary.md",
             "redirect_url": "/dotnet/core/compatibility/serialization/7.0/serializationformat-binary",
-            "redirect_document_id": true    
+            "redirect_document_id": true
         },
         {
             "source_path_from_root": "/docs/core/compatibility/extensions/6.0/bind-single-elements-to-array.md",
@@ -143,6 +143,10 @@
             "source_path_from_root": "/docs/core/compatibility/sdk/6.0/implicit-namespaces-rc1.md",
             "redirect_url": "/dotnet/core/compatibility/6.0"
         },
+        {
+            "source_path_from_root": "/docs/core/compatibility/sdk/8.0/tool-rollforward.md",
+            "redirect_url": "/dotnet/core/compatibility/8.0"
+        },
         {
             "source_path_from_root": "/docs/core/compatibility/serialization.md",
             "redirect_url": "/dotnet/core/compatibility/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions"

@@ -111,16 +111,18 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 
 | Title                                                                                              | Type of change                                   | Introduced |
 | -------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------- |
-| [.NET tool roll-forward behavior](sdk/8.0/tool-rollforward.md)                                     | Behavioral change                                | Preview 5  |
 | [CLI console output uses UTF-8](sdk/8.0/console-encoding.md)                                       | Behavioral change/Source and binary incompatible | Preview 1  |
 | [Console encoding not UTF-8 after completion](sdk/8.0/console-encoding-fix.md)                     | Behavioral change/Binary incompatible            | Preview 3  |
 | [Containers default to use the 'latest' tag](sdk/8.0/default-image-tag.md)                         | Behavioral change                                | Preview 6  |
 | ['dotnet pack' uses Release configuration](sdk/8.0/dotnet-pack-config.md)                          | Behavioral change/Source incompatible            | Preview 1  |
 | ['dotnet publish' uses Release configuration](sdk/8.0/dotnet-publish-config.md)                    | Behavioral change/Source incompatible            | Preview 1  |
+| [MSBuild custom derived build events deprecated](sdk/8.0/custombuildeventargs.md)                  | Behavioral change                  | RC 1       |
 | [MSBuild respects DOTNET_CLI_UI_LANGUAGE](sdk/8.0/msbuild-language.md)                             | Behavioral change                                | Preview 5  |
 | [Runtime-specific apps not self-contained](sdk/8.0/runtimespecific-app-default.md)                 | Source/binary incompatible                       | Preview 5  |
 | ['dotnet restore' produces security vulnerability warnings](sdk/8.0/dotnet-restore-audit.md)       | Behavioral change                                | Preview 4  |
+| [SDK uses a smaller RID graph](sdk/8.0/rid-graph.md)                                               | Behavioral change/Source incompatible            | RC 1  |
 | [Trimming may not be used with .NET Standard or .NET Framework](sdk/8.0/trimming-unsupported-targetframework.md) | Behavioral change                                | RC 1       |
+| [Version requirements for .NET 8 SDK](sdk/8.0/version-requirements.md)                             |                | RC 1       |
 
 ## Serialization
 

@@ -5,7 +5,7 @@ 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 <xref:System.Runtime.Loader.AssemblyDependencyResolver>.
+When running an application with [runtime identifier (RID)](../../../rid-catalog.md) specific assets, the host determines what assets are relevant for the platform on which it's running. This applies to both the application itself and the resolution logic used by <xref:System.Runtime.Loader.AssemblyDependencyResolver>.
 
 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.
 
@@ -74,3 +74,7 @@ If you need to revert to the previous behavior, set the backwards compatibility
 ## Affected APIs
 
 - <xref:System.Runtime.Loader.AssemblyDependencyResolver?displayProperty=fullName>
+
+## See also
+
+- [.NET SDK uses a smaller RID graph](../../sdk/8.0/rid-graph.md)
@@ -0,0 +1,47 @@
+---
+title: "Breaking change: MSBuild custom derived build events deprecated"
+description: Learn about the breaking change in MSBuild where custom derived build events have been deprecated.
+ms.date: 09/05/2023
+---
+# MSBuild custom derived build events deprecated
+
+Custom derived build events of any subclass of <xref:Microsoft.Build.Framework.BuildEventArgs> by any build extensibility (mainly custom tasks) have been deprecated.
+
+## Previous behavior
+
+Previously, you could derive from any subclass of <xref:Microsoft.Build.Framework.BuildEventArgs> and use those types freely in custom tasks and other build extensibility points.
+
+## New behavior
+
+Starting in .NET 8, a build error is issued if your code uses any type derived from <xref:Microsoft.Build.Framework.BuildEventArgs> and you build using the .NET 8 version of MSBuild, that is, from the command line:
+
+> Usage of unsecure BinaryFormatter during serialization of custom event type 'MyCustomBuildEventArgs'. This will be deprecated soon. Please use Extended*EventArgs instead. More info: <https://aka.ms/msbuild/eventargs>
+
+If you build from Visual Studio, there is no change in behavior unless you opt in by setting the `MSBUILDCUSTOMBUILDEVENTWARNING` environment variable to 1 (available in Visual Studio version 17.8 and later).
+
+## Version introduced
+
+.NET 8 RC 1
+
+## Type of change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+<xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> serialization is obsolete in .NET 8 and later versions. Any use of <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> throws an exception at run time. Since MSBuild custom derived build events use <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter>, your build would crash if you use these events in your build. The new build error provides a more graceful failure.
+
+## Recommended action
+
+Use one of the following newly introduced, built-in events for extensibility instead of your custom derived build event:
+
+- `Microsoft.Build.Framework.ExtendedCustomBuildEventArgs`
+- `Microsoft.Build.Framework.ExtendedBuildErrorEventArgs`
+- `Microsoft.Build.Framework.ExtendedBuildMessageEventArgs`
+- `Microsoft.Build.Framework.ExtendedBuildWarningEventArgs`
+
+Alternatively, you can temporarily disable the check by explicitly setting the environment variable `MSBUILDCUSTOMBUILDEVENTWARNING` to something other than 1.
+
+## Affected APIs
+
+- <xref:Microsoft.Build.Framework.CustomBuildEventArgs?displayProperty=fullName>
@@ -0,0 +1,38 @@
+---
+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
+---
+# .NET SDK uses a smaller RID graph
+
+Projects that target .NET 8 or later versions now use a smaller, "portable" runtime identifier (RID) graph.
+
+## Previous behavior
+
+The .NET SDK used a complex [RID graph](../../../rid-catalog.md) to determine assets when building or publishing a project.
+
+## 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.
+
+## Version introduced
+
+.NET 8 RC 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change) and can also affect [source compatibility](../../categories.md#source-compatibility).
+
+## 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-<arch>`, `linux-musl-<arch>`, `osx-<arch>`, and `win-<arch>`.
+
+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.
+
+## See also
+
+- [Host determines RID-specific assets](../../deployment/8.0/rid-asset-list.md)
@@ -3,24 +3,24 @@ title: "Breaking change: Trimming may not be used with .NET Standard or .NET Fra
 description: Learn about a breaking change in the .NET 8 SDK where trimming settings produce new warnings or errors in .NET Standard or .NET Framework projects.
 ms.date: 08/21/2023
 ---
-# Trimming may not be used with .NET standard or .NET framework
+# Trimming may not be used with .NET Standard or .NET Framework
 
 Projects that set `<PublishTrimmed>true</PublishTrimmed>`, `<IsTrimmable>true</IsTrimmable>` or `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` with a `TargetFramework` that is any version of .NET Standard or .NET Framework produce a warning or error because trimming is unsupported for these target frameworks.
 
 ## Previous behavior
 
 Previously, when used in a .NET Standard or .NET Framework project, these settings behaved as follows:
 
-- `<PublishTrimmed>true</PublishTrimmed>` would have no effect.
-- `<IsTrimmable>true</IsTrimmable>` would embed an assembly-level attribute `[assembly: AssemblyMetadata("IsTrimmable", "true")]` into the output assembly. That attribute opted the assembly into trimming when consumed in a trimmed app (even an app that uses `<TrimMode>partial</TrimMode>`).
-- `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` would enable trim analysis for the library, using the .NET Standard or .NET Framework reference assemblies corresponding to the library's `TargetFramework` even though these reference assemblies aren't annotated for trimming.
+- `<PublishTrimmed>true</PublishTrimmed>` had no effect.
+- `<IsTrimmable>true</IsTrimmable>` embedded an assembly-level attribute `[assembly: AssemblyMetadata("IsTrimmable", "true")]` into the output assembly. That attribute opted the assembly into trimming when consumed in a trimmed app (even an app that uses `<TrimMode>partial</TrimMode>`).
+- `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` enabled trim analysis for the library, using the .NET Standard or .NET Framework reference assemblies corresponding to the library's `TargetFramework` even though these reference assemblies aren't annotated for trimming.
 
 ## New behavior
 
 Starting in the .NET 8 SDK, in a project targeting .NET Standard or .NET Framework:
 
 - `<PublishTrimmed>` produces an error indicating that this setting is unsupported for the target framework.
-- `<IsTrimmable>` or `<EnableTrimAnalyzer>` produce a warning indicating that `<IsTrimmable>` is unsupported for the target framework. These settings otherwise have no effect on the build output.
+- `<IsTrimmable>` and `<EnableTrimAnalyzer>` produce a warning indicating that `<IsTrimmable>` is unsupported for the target framework. These settings otherwise have no effect on the build output.
 
 ## Version introduced
 

@@ -0,0 +1,36 @@
+---
+title: "Breaking change: Version requirements for .NET 8 SDK"
+description: Learn about the breaking change in the .NET 8 SDK where specific versions of Visual Studio and MSBuild are required.
+ms.date: 09/05/2023
+---
+# Version requirements for .NET 8 SDK
+
+Per the [published support rules](../../../porting/versioning-sdk-msbuild-vs.md#targeting-and-support-rules), we update the minimum Visual Studio and MSBuild version for each new major release with a one quarter delay. For the .NET 8 release, 8.0.100 requires version 17.7 to be loaded but only supports targeting .NET 7 in that version. To target `net8.0`, you must use version 17.8 or later.
+
+## Version introduced
+
+.NET SDK 8 RC 1
+
+## Previous behavior
+
+.NET 8.0.1xx-preview1 required version 17.4 of Visual Studio and MSBuild. .NET 8.0.1xx-preview4 required version 17.6 of Visual Studio and MSBuild.
+
+## New behavior
+
+Versions 8.0.1xx of the .NET SDK require Visual Studio version 17.7 and MSBuild version 17.7.
+
+## Reason for change
+
+This is our standard support policy for the SDK as we can't support all prior versions of Visual Studio and MSBuild.
+
+## Recommended action
+
+Upgrade your Visual Studio version to the required version.
+
+## Affected APIs
+
+N/A
+
+## See also
+
+- [Targeting and support rules](../../../porting/versioning-sdk-msbuild-vs.md#targeting-and-support-rules)
@@ -116,8 +116,6 @@ items:
         href: reflection/8.0/function-pointer-reflection.md
     - name: SDK and MSBuild
       items:
-      - name: .NET tool roll-forward behavior
-        href: sdk/8.0/tool-rollforward.md
       - name: CLI console output uses UTF-8
         href: sdk/8.0/console-encoding.md
       - name: Console encoding not UTF-8 after completion
@@ -130,12 +128,18 @@ items:
         href: sdk/8.0/dotnet-publish-config.md
       - name: "'dotnet restore' produces security vulnerability warnings"
         href: sdk/8.0/dotnet-restore-audit.md
+      - name: MSBuild custom derived build events deprecated
+        href: sdk/8.0/custombuildeventargs.md
       - name: MSBuild respects DOTNET_CLI_UI_LANGUAGE
         href: sdk/8.0/msbuild-language.md
       - name: Runtime-specific apps not self-contained
         href: sdk/8.0/runtimespecific-app-default.md
+      - name: SDK uses a smaller RID graph
+        href: sdk/8.0/rid-graph.md
       - name: Trimming may not be used with .NET Standard or .NET Framework
         href: sdk/8.0/trimming-unsupported-targetframework.md
+      - name: Version requirements for .NET 8 SDK
+        href: sdk/8.0/version-requirements.md
     - name: Serialization
       items:
       - name: BinaryFormatter disabled for most projects
@@ -1464,8 +1468,6 @@ items:
     items:
     - name: .NET 8
       items:
-      - name: .NET tool roll-forward behavior
-        href: sdk/8.0/tool-rollforward.md
       - name: CLI console output uses UTF-8
         href: sdk/8.0/console-encoding.md
       - name: Console encoding not UTF-8 after completion
@@ -1478,12 +1480,18 @@ items:
         href: sdk/8.0/dotnet-publish-config.md
       - name: "'dotnet restore' produces security vulnerability warnings"
         href: sdk/8.0/dotnet-restore-audit.md
+      - name: MSBuild custom derived build events deprecated
+        href: sdk/8.0/custombuildeventargs.md
       - name: MSBuild respects DOTNET_CLI_UI_LANGUAGE
         href: sdk/8.0/msbuild-language.md
       - name: Runtime-specific apps not self-contained
         href: sdk/8.0/runtimespecific-app-default.md
+      - name: SDK uses a smaller RID graph
+        href: sdk/8.0/rid-graph.md
       - name: Trimming may not be usedwith .NET Standard or .NET Framework
         href: sdk/8.0/trimming-unsupported-targetframework.md
+      - name: Version requirements for .NET 8 SDK
+        href: sdk/8.0/version-requirements.md
     - name: .NET 7
       items:
       - name: Automatic RuntimeIdentifier for certain projects

@@ -18,7 +18,6 @@ Welcome to what's new in the .NET docs for June 2023. This article lists some of
 - [Base64.DecodeFromUtf8 methods ignore whitespace](../core/compatibility/core-libraries/8.0/decodefromutf8-whitespace.md)
 - [Host determines RID-specific assets](../core/compatibility/deployment/8.0/rid-asset-list.md)
 - [MSBuild respects DOTNET_CLI_UI_LANGUAGE](../core/compatibility/sdk/8.0/msbuild-language.md)
-- [.NET tool roll-forward behavior](../core/compatibility/sdk/8.0/tool-rollforward.md)
 - [SafeHandle types must have public constructor](../core/compatibility/interop/8.0/safehandle-constructor.md)
 - [IndexOfAnyValues renamed to SearchValues](../core/compatibility/core-libraries/8.0/indexofanyvalues-renamed.md)
 - [Runtime-specific apps no longer self-contained](../core/compatibility/sdk/8.0/runtimespecific-app-default.md)