sdk breaking changes (#43371)

dotnet · Nov 11, 2024 · e7999d4 · e7999d4
1 parent 6d02d4a
commit e7999d4
Show file tree

Hide file tree

Showing 7 changed files with 133 additions and 15 deletions.
diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md
@@ -99,12 +99,14 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 | [`dotnet workload` commands output change](sdk/9.0/dotnet-workload-output.md) | Behavioral change | Preview 1          |
 | [`installer` repo version no longer documented](sdk/9.0/productcommits-versions.md) | Behavioral change | Preview 5    |
 | [Terminal logger is default](sdk/9.0/terminal-logger.md)                      | Behavioral change | Preview 1          |
-| [Warning emitted for .NET Standard 1.x](sdk/9.0/netstandard-warning.md)       | Source incompatible | Preview 6        |
+| [Version requirements for .NET 9 SDK](sdk/9.0/version-requirements.md)        | Source incompatible | GA              |
+| [Warning emitted for .NET Standard 1.x target](sdk/9.0/netstandard-warning.md) | Source incompatible | Preview 6       |
+| [Warning emitted for .NET 7 target](sdk/9.0/net70-warning.md)                 | Source incompatible | GA               |
 
 ## Serialization
 
-| Title                                                                       | Type of change    | Introduced version |
-|-----------------------------------------------------------------------------|-------------------|--------------------|
+| Title                                                                         | Type of change    | Introduced version |
+|-------------------------------------------------------------------------------|-------------------|--------------------|
 | [BinaryFormatter always throws](serialization/9.0/binaryformatter-removal.md) | Behavioral change | Preview 6          |
 
 ## Windows Forms

diff --git a/docs/core/compatibility/sdk/8.0/version-requirements.md b/docs/core/compatibility/sdk/8.0/version-requirements.md
@@ -39,7 +39,7 @@ This change can affect [source compatibility](../../categories.md#source-compati
 
 ## 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.
+This is part of the standard support policy for the SDK as not all prior versions of Visual Studio and MSBuild can be supported.
 
 ## Recommended action
 

diff --git a/docs/core/compatibility/sdk/9.0/net70-warning.md b/docs/core/compatibility/sdk/9.0/net70-warning.md
@@ -0,0 +1,60 @@
+---
+title: "Breaking change: Warning emitted when targeting net7.0"
+description: Learn about the breaking change in the .NET SDK where a warning is issued for apps that target net7.0, which is out of support.
+ms.date: 11/6/2024
+---
+
+# Warning emitted when targeting net7.0
+
+Starting with the November 2024 releases of the .NET 8 and 9 SDKs, warning [NETSDK1138](../../../tools/sdk-errors/netsdk1138.md) is issued if your app targets `net7.0`. .NET 7 is now out of support.
+
+When a version of .NET goes out of support, it's marked as such in Visual Studio the following month. The .NET SDK waits 6 months before adding a warning.
+
+This change applies to .NET 8.0.111, 8.0.307, 8.0.404, and 9.0.100.
+
+## Version introduced
+
+.NET 9 GA
+
+## Previous behavior
+
+Previously, apps could target `net7.0` without a warning, even though it was out of support.
+
+## New behavior
+
+Starting in .NET 9 and the other [affected versions](#version-introduced), the following warning is issued at compile time for apps that target `net7.0`:
+
+> warning NETSDK1138: The target framework 'net7.0' is out of support
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+This is a planned change to ensure that customers are aware that they're targeting an unsupported framework version.
+
+## Recommended action
+
+Upgrade your app to target `net8.0`.
+
+If you must continue targeting `net7.0`, you can set the MSBuild property `CheckEolTargetFramework` to `false`. You can set it in the project file or by passing `/p:CheckEolTargetFramework=false` to a .NET CLI command such as `dotnet build`.
+
+Example *.csproj* or *.vbproj* file:
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    ...
+    <CheckEolTargetFramework>false</CheckEolTargetFramework>
+  </PropertyGroup>
+</Project>
+```
+
+## Affected APIs
+
+None.
+
+## See also
+
+- [NETSDK1138: The target framework is out of support](../../../tools/sdk-errors/netsdk1138.md)
diff --git a/docs/core/compatibility/sdk/9.0/version-requirements.md b/docs/core/compatibility/sdk/9.0/version-requirements.md
@@ -0,0 +1,47 @@
+---
+title: "Breaking change: Version requirements for .NET 9 SDK"
+description: Learn about the breaking change in the .NET 9 SDK where specific versions of Visual Studio and MSBuild are required.
+ms.date: 11/06/2024
+---
+# Version requirements for .NET 9 SDK
+
+Per the [published support rules](../../../porting/versioning-sdk-msbuild-vs.md#targeting-and-support-rules), the minimum Visual Studio and MSBuild version for each new major release is updated with a one quarter delay. For the .NET 9 release:
+
+- 9.0.100 requires version 17.11 to target `net8.0` and earlier frameworks.
+- 9.0.100 requires version 17.12 or later to target `net9.0`.
+
+## Version introduced
+
+.NET 9 GA
+
+## Previous behavior
+
+Previously, you could load .NET 9.0.100 on earlier Visual Studio versions. In addition, there was no warning when targeting `net9.0` in Visual Studio version 17.11.
+
+## New behavior
+
+- .NET 9.0.100 won't load in Visual Studio version 17.10 or earlier.
+- Visual Studio version 17.11 doesn't make `net9.0` available in the project properties.
+- .NET 9.0.100 warns when targeting `net9.0` and using Visual Studio version 17.11:
+
+  > NETSDK1223: Targeting .NET 9.0 or higher in Visual Studio 2022 17.11 is not supported.
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+This is part of the standard support policy for the SDK as not all prior versions of Visual Studio and MSBuild can be supported.
+
+## 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)
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -102,8 +102,12 @@ items:
                 href: sdk/9.0/productcommits-versions.md
               - name: Terminal logger is default
                 href: sdk/9.0/terminal-logger.md
+              - name: Version requirements
+                href: sdk/9.0/version-requirements.md
               - name: Warning emitted for .NET Standard 1.x targets
                 href: sdk/9.0/netstandard-warning.md
+              - name: Warning emitted for .NET 7 target
+                href: sdk/9.0/net70-warning.md
           - name: Serialization
             items:
               - name: BinaryFormatter always throws
@@ -1780,8 +1784,12 @@ items:
                 href: sdk/9.0/productcommits-versions.md
               - name: Terminal logger is default
                 href: sdk/9.0/terminal-logger.md
+              - name: Version requirements for .NET 9 SDK
+                href: sdk/9.0/version-requirements.md
               - name: Warning emitted for .NET Standard 1.x targets
                 href: sdk/9.0/netstandard-warning.md
+              - name: Warning emitted for .NET 7 target
+                href: sdk/9.0/net70-warning.md
           - name: .NET 8
             items:
               - name: CLI console output uses UTF-8

diff --git a/docs/core/porting/versioning-sdk-msbuild-vs.md b/docs/core/porting/versioning-sdk-msbuild-vs.md
@@ -4,7 +4,7 @@ description: Learn about the versioning relationship between the .NET SDK and MS
 author: StephenBonikowsky
 ms.author: stebon
 ms.custom: updateeachrelease
-ms.date: 11/15/2023
+ms.date: 11/06/2024
 ---
 # .NET SDK, MSBuild, and Visual Studio versioning
 
@@ -34,6 +34,10 @@ The support timeframe for the SDK typically matches that of the Visual Studio ve
 | 5.0.2xx     | 16.9                          | March '21 | May '22   |
 | 5.0.3xx     | 16.10                         | May '21   | Aug '21   |
 | 5.0.4xx     | 16.11                         | Aug '21   | May '22   |
+| 6.0.1xx     | 17.0                          | Nov '21   | Nov '24   |
+| 6.0.2xx     | 17.1                          | Feb '22   | May '22   |
+| 6.0.3xx     | 17.2<sup>3</sup>              | May '22   | Oct '23   |
+| 6.0.4xx     | 17.3                          | Aug '22   | Nov '24   |
 | 7.0.1xx     | 17.4                          | Nov '22   | May '24   |
 | 7.0.2xx     | 17.5<sup>3</sup>              | Feb '23   | May '23   |
 | 7.0.3xx     | 17.6                          | May '23   | May '24   |
@@ -46,12 +50,8 @@ The support timeframe for the SDK typically matches that of the Visual Studio ve
 
 | SDK version | MSBuild/Visual Studio version | Ship date | Lifecycle           |
 |-------------|-------------------------------|-----------|---------------------|
-| 6.0.1xx     | 17.0                          | Nov '21   | Nov '24<sup>1</sup> |
-| 6.0.2xx     | 17.1                          | Feb '22   | May '22             |
-| 6.0.3xx     | 17.2<sup>3</sup>              | May '22   | Oct '23             |
-| 6.0.4xx     | 17.3                          | Aug '22   | Nov '24<sup>2</sup> |
 | 8.0.1xx     | 17.8                          | Nov '23   | Nov '25<sup>1</sup> |
-| 8.0.2xx     | 17.9<sup>3</sup>              | Feb '24   | May '24             |
+| 8.0.2xx     | 17.9<sup>3</sup>              | Feb '24   | May '24<sup>3</sup> |
 | 8.0.3xx     | 17.10                         | May '24   | TBD                 |
 | 8.0.4xx     | 17.11                         | Aug '24   | Nov '25<sup>2</sup> |
 | 9.0.1xx     | 17.12                         | Nov '24   | May '26<sup>1</sup> |
@@ -65,15 +65,15 @@ The support timeframe for the SDK typically matches that of the Visual Studio ve
 >
 > <sup>2</sup> .4xx .NET SDK feature bands are supported for the life of the matching runtime as stand-alone installs.
 >
-> <sup>3</sup> 6.0.300, 7.0.200, and 8.0.200 require newer Visual Studio versions. For more information, see the [support rules](#targeting-and-support-rules).
+> <sup>3</sup> 8.0.200 requires a newer Visual Studio version. For more information, see the [support rules](#targeting-and-support-rules).
 >
 > [Visual Studio 2019 Lifecycle](/lifecycle/products/visual-studio-2019)
 >
 > [Visual Studio 2022 Lifecycle](/lifecycle/products/visual-studio-2022)
 
 ## Targeting and support rules
 
-Starting with .NET SDK 7.0.100 and .NET SDK 6.0.300, a policy has been put into place regarding which versions of MSBuild and Visual Studio a given version of the .NET SDK will run in. The policy is:
+A the following policy dictates which versions of MSBuild and Visual Studio a given version of the .NET SDK will run in:
 
 - Each new TargetFramework **requires** a new Visual Studio version or a new `dotnet` version.
 - The first version of Visual Studio that supports a new TargetFramework becomes a floor for the feature bands of that SDK for Roslyn API surface, MSBuild targets, source generators, analyzers, and so on.
@@ -95,15 +95,15 @@ Starting with .NET SDK 7.0.100 and .NET SDK 6.0.300, a policy has been put into
 | 9.0.100 | 17.12 | 17.11            | Net8.0 | Net9.0 |
 
 > [!NOTE]
-> The table depicts how these versioning rules will be applied going forward, starting with .NET SDK 7.0.100 and .NET SDK 6.0.300. It also depicts how the policy would have applied to previously shipped versions of the .NET SDK, had it been in place then. However, the requirements for previous versions of the SDK don't change&mdash;that is, the minimum required version of Visual Studio for .NET SDK 6.0.100 or 6.0.200 remains 16.10.
+> The table depicts how these versioning rules are applied, starting with .NET SDK 7.0.100 and .NET SDK 6.0.300. It also depicts how the policy would have applied to previously shipped versions of the .NET SDK, had it been in place then. However, the requirements for previous versions of the SDK don't change&mdash;that is, the minimum required version of Visual Studio for .NET SDK 6.0.100 or 6.0.200 remains 16.10.
 
 > <sup>1</sup> A breaking change in 7.0.300 for Blazor and Razor development requires Visual Studio version 17.6 or newer. For more information, see [dotnet/razor issue 8718](https://github.com/dotnet/razor/issues/8718).
 
 To ensure consistent tooling, you should use `dotnet build` rather than `msbuild` to build your application when possible.
 
 ## Preview versioning
 
-Major versions of the .NET SDK are typically released within a few days of a Visual Studio preview version. While there may be other combinations that work, only the latest preview released is tested and officially supported. The following table shows which version of Visual Studio each .NET preview version was tested with prior to release.
+Major versions of the .NET SDK are typically released within a few days of a Visual Studio preview version. While there might be other combinations that work, only the latest preview released is tested and officially supported. The following table shows which version of Visual Studio each .NET preview version was tested with prior to release.
 
 | SDK preview version | Visual Studio version |
 |---------------------|-----------------------|
@@ -116,6 +116,7 @@ Major versions of the .NET SDK are typically released within a few days of a Vis
 | 9.0.100 Preview 7   | 17.12 Preview 1       |
 | 9.0.100 RC 1        | 17.12 Preview 2       |
 | 9.0.100 RC 2        | 17.12 Preview 3       |
+| 9.0.100 GA          | 17.12 GA              |
 
 ## Reference
 

diff --git a/docs/core/tools/sdk-errors/netsdk1138.md b/docs/core/tools/sdk-errors/netsdk1138.md
@@ -16,7 +16,7 @@ Out-of-support versions include 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, and 5.0.
 
 To resolve this error, change your project to target a supported version of .NET.
 
-If you want to suppress the message without targeting a later framework, set the MSBuild property `CheckEolTargetFramework` to false. You can set it in the project file or by passing `/p:CheckEolTargetFramework=false` to a .NET CLI command, such as `dotnet build`. Here's an example project file:
+If you want to suppress the message without targeting a later framework, set the MSBuild property `CheckEolTargetFramework` to `false`. You can set it in the project file or by passing `/p:CheckEolTargetFramework=false` to a .NET CLI command, such as `dotnet build`. Here's an example project file:
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">