Skip to content

Commit e4d5897

Browse files
CopilotCopilot
authored
Document .NET 10 SDK version requirements breaking change (#48923)
1 parent 54cefea commit e4d5897

File tree

4 files changed

+55
-3
lines changed

4 files changed

+55
-3
lines changed

‎docs/core/compatibility/10.0.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
125125
| [NuGet packages with no runtime assets aren't included in deps.json](sdk/10.0/deps-json-trimmed-packages.md) | Source incompatible | Preview 5 |
126126
| [PackageReference without a version raises an error](sdk/10.0/nu1015-packagereference-version.md) | Behavioral change | Preview 6 |
127127
| [PrunePackageReference privatizes direct prunable references](sdk/10.0/prune-packagereference-privateassets.md) | Behavioral change | Preview 7 |
128+
| [Version requirements for .NET 10 SDK](sdk/10.0/version-requirements.md) | Behavioral change | RC 2 |
128129
| [HTTP warnings promoted to errors in `dotnet package list` and `dotnet package search`](sdk/10.0/http-warnings-to-errors.md) | Behavioral/source incompatible change | Preview 4 |
129130
| [NUGET_ENABLE_ENHANCED_HTTP_RETRY environment variable removed](sdk/10.0/nuget-enhanced-http-retry-removed.md) | Behavioral change | Preview 6 |
130131
| [NuGet logs an error for invalid package IDs](sdk/10.0/nuget-packageid-validation.md) | Behavioral change | RC 1 |

‎docs/core/compatibility/sdk/10.0/version-requirements.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "Breaking change: Version requirements for .NET 10 SDK"
3+
description: Learn about the breaking change in the .NET 10 SDK where specific versions of Visual Studio and MSBuild are required.
4+
ms.date: 10/08/2025
5+
ai-usage: ai-generated
6+
---
7+
# Version requirements for .NET 10 SDK
8+
9+
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 10 release:
10+
11+
- 10.0.100 requires version 17.14 to be loaded but only supports targeting .NET 9 in that version.
12+
- To target `net10.0`, you must use version 18.0 or later.
13+
14+
## Version introduced
15+
16+
.NET 10 RC 2
17+
18+
## Previous behavior
19+
20+
The previous minimum Visual Studio version for .NET 10 previews was 17.13 to allow time for release and more adoption of Visual Studio version 17.14.
21+
22+
## New behavior
23+
24+
- .NET 10.0.100 will only load on Visual Studio version 17.14 or later.
25+
- .NET 10.0.100 warns when targeting `net10.0` on Visual Studio version 17.14. To target `net10.0`, you must use Visual Studio version 18.0 or later.
26+
27+
## Type of breaking change
28+
29+
This change is a [behavioral change](../../categories.md#behavioral-change).
30+
31+
## Reason for change
32+
33+
This change is part of the standard support policy for the SDK as not all prior versions of Visual Studio and MSBuild can be supported.
34+
35+
## Recommended action
36+
37+
Upgrade to Visual Studio 2026 to target `net10.0`. If you only need to target `net9.0` or earlier, you can use Visual Studio version 17.14 or later.
38+
39+
## Affected APIs
40+
41+
N/A
42+
43+
## See also
44+
45+
- [Targeting and support rules](../../../porting/versioning-sdk-msbuild-vs.md#targeting-and-support-rules)

‎docs/core/compatibility/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,8 @@ items:
160160
href: sdk/10.0/nu1015-packagereference-version.md
161161
- name: PrunePackageReference privatizes direct prunable references
162162
href: sdk/10.0/prune-packagereference-privateassets.md
163+
- name: Version requirements for .NET 10 SDK
164+
href: sdk/10.0/version-requirements.md
163165
- name: Windows Forms
164166
items:
165167
- name: API obsoletions

‎docs/core/porting/versioning-sdk-msbuild-vs.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Learn about the versioning relationship between the .NET SDK and MS
44
author: StephenBonikowsky
55
ms.author: stebon
66
ms.custom: updateeachrelease
7-
ms.date: 11/06/2024
7+
ms.date: 10/08/2025
88
---
99
# .NET SDK, MSBuild, and Visual Studio versioning
1010

@@ -19,7 +19,7 @@ For example, version 7.0.203 ships with .NET 7, is the second minor Visual Studi
1919
An installation of Visual Studio includes a single matching copy of the .NET SDK. If you update your Visual Studio instance, the .NET SDK installed by Visual Studio is also updated, including across .NET SDK feature bands and major bands. If you want to use a different .NET SDK than what's installed by Visual Studio, you can install it from the [.NET download page](https://aka.ms/dotnet/download), and Visual Studio upgrade won't touch that version. You're responsible for updating that copy of the .NET SDK from then on.
2020

2121
> [!NOTE]
22-
The .NET SDK supports targeting down-level versions of .NET, so we recommend always updating your .NET SDK along with your Visual Studio version.
22+
> The .NET SDK supports targeting down-level versions of .NET, so we recommend always updating your .NET SDK along with your Visual Studio version.
2323
2424
## Lifecycle
2525

@@ -74,7 +74,7 @@ The support timeframe for the SDK typically matches that of the Visual Studio ve
7474
7575
## Targeting and support rules
7676

77-
A the following policy dictates which versions of MSBuild and Visual Studio a given version of the .NET SDK will run in:
77+
The following policy dictates which versions of MSBuild and Visual Studio a given version of the .NET SDK will run in:
7878

7979
- Each new TargetFramework **requires** a new Visual Studio version or a new `dotnet` version.
8080
- 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.
@@ -89,13 +89,16 @@ A the following policy dictates which versions of MSBuild and Visual Studio a gi
8989
| 9.0.100 | 17.12 | 17.11 | Net8.0 | Net9.0 |
9090
| 9.0.200 | 17.13 | 17.12 | Net9.0 | Net9.0 |
9191
| 9.0.300 | 17.14 | 17.12 | Net9.0 | Net9.0 |
92+
| 10.0.100 | 18.0 | 17.14 | Net9.0 | Net10.0 |
9293

9394
> [!NOTE]
9495
> 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—that is, the minimum required version of Visual Studio for .NET SDK 6.0.100 or 6.0.200 remains 16.10.
9596
>
9697
> Targeting `net8.0` is officially supported in Visual Studio 17.8+ only.
9798
>
9899
> Targeting `net9.0` is officially supported in Visual Studio 17.12+ only.
100+
>
101+
> Targeting `net10.0` is officially supported in Visual Studio 18.0+ only.
99102
100103
To ensure consistent tooling, you should use `dotnet build` rather than `msbuild` to build your application when possible.
101104

@@ -111,6 +114,7 @@ Major versions of the .NET SDK are typically released within a few days of a Vis
111114
| 10.0.100 Preview 1 | 17.14 Preview 1 |
112115
| 10.0.100 Preview 2 | 17.14 Preview 2 |
113116
| 10.0.100 Preview 3 | 17.14 Preview 3 |
117+
| 10.0.100 RC 2 | 17.14 |
114118

115119
## Reference
116120

0 commit comments

Comments
 (0)