Update SDK versioning document to include support matrix guidance #51412
+37
−11
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,6 +1,6 @@ | ||||||
| --- | ||||||
| title: .NET SDK, MSBuild, and Visual Studio versioning | ||||||
| description: Learn about the versioning relationship between the .NET SDK and MSBuild/Visual Studio. | ||||||
| author: StephenBonikowsky | ||||||
| ms.custom: updateeachrelease | ||||||
| ms.date: 10/23/2025 | ||||||
|
|
@@ -11,12 +11,14 @@ | |||||
|
|
||||||
| ## Versioning | ||||||
|
|
||||||
| The first part of the .NET SDK version matches the .NET version that it includes, runs on, and targets by default. The feature band starts at 1 and increases for each quarterly .NET SDK release. The patch version increments with each month's servicing updates. | ||||||
|
|
||||||
| For example, version 7.0.203 ships with .NET 7, is the second quarterly feature band release since 7.0.100 first came out, and is the third patch since 7.0.200 released. | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| Starting in Visual Studio 18.0, there are monthly minor versions of Visual Studio but the .NET SDK will remain quarterly. The in-between Visual Studio releases will contain patch versions of the latest current .NET SDK version. | ||||||
|
There was a problem hiding this comment. The Visual Studio 18.0 sentence is a run-on and mixes tenses. Rephrase to improve readability (for example, split into two sentences and keep it in present tense).
Suggested change
|
||||||
|
|
||||||
| > [!NOTE] | ||||||
| > The .NET SDK supports targeting down-level versions of .NET, so we recommend always updating your .NET SDK along with your Visual Studio version. | ||||||
|
|
||||||
|
|
@@ -60,13 +62,14 @@ | |||||
| | 8.0.4xx | 17.11 | Aug '24 | Nov '26<sup>2</sup> | | ||||||
| | 9.0.1xx | 17.12 | Nov '24 | May '26 | | ||||||
| | 9.0.2xx | 17.13 | Feb '25 | May '25 | | ||||||
| | 9.0.3xx | 17.14 | May '25 | Nov '26<sup>2</sup> | | ||||||
|
There was a problem hiding this comment. This table row has extra trailing whitespace, which makes the markdown table harder to maintain and review. Trim the extra padding so the row formatting matches the rest of the table. |
||||||
| | 10.0.1xx | 18.0 | Nov '25 | Nov '28 | | ||||||
| | 10.0.2xx | 18.4 | Mar '26 | May '26 | | ||||||
|
|
||||||
| > [!NOTE] | ||||||
| > <sup>1</sup> .1xx .NET SDK feature bands are supported throughout the lifecycle of major .NET versions. During the extended support period, support is limited to security fixes and minimal high-priority non-security fixes for Linux only. To learn more about the reasoning for this extended support, see [Source-build support](https://github.com/dotnet/source-build#support). | ||||||
| > | ||||||
| > <sup>2</sup> The final .NET SDK feature bands of a major version are supported for the life of the matching runtime as stand-alone installs. | ||||||
| > | ||||||
| > [Visual Studio 2026 lifecycle](/lifecycle/products/visual-studio-2026) | ||||||
| > | ||||||
|
|
@@ -92,6 +95,7 @@ | |||||
| | 9.0.200 | 17.13 | 17.12 | Net9.0 | Net9.0 | | ||||||
| | 9.0.300 | 17.14 | 17.12 | Net9.0 | Net9.0 | | ||||||
| | 10.0.100 | 18.0 | 17.14 | Net9.0 | Net10.0 | | ||||||
| | 10.0.200 | 18.4 | 18.0 | Net10.0 | Net10.0 | | ||||||
|
|
||||||
| > [!NOTE] | ||||||
| > 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. | ||||||
|
|
@@ -104,20 +108,42 @@ | |||||
|
|
||||||
| To ensure consistent tooling, you should use `dotnet build` rather than `msbuild` to build your application when possible. | ||||||
|
|
||||||
| ## SDK and Visual Studio support matrix | ||||||
|
|
||||||
| While most developers use the .NET SDK bundled with their Visual Studio version, some configurations involve mismatched SDK and Visual Studio versions. We cannot ensure every Visual Studio version works with every in-support .NET SDK but rather test the most common configurations and make a best effort to ensure compatibility. | ||||||
|
|
||||||
|
Comment on lines
+113
to
+114
There was a problem hiding this comment. This section uses first-person language ("We cannot…", "we'll…"), which is inconsistent with the second-person voice used throughout the porting docs (for example, docs/core/porting/framework-overview.md:11 and docs/core/porting/modernize.md:13). Rewrite in second person or neutral/passive voice so the guidance addresses the reader directly. |
||||||
| ### Backward and forward compatibility | ||||||
|
|
||||||
| - **Primary supported configuration**: Use the SDK version bundled with your Visual Studio installation | ||||||
| - Visual Studio 17.14 and .NET 9.0.3xx | ||||||
|
Check failure on line 118 in docs/core/porting/versioning-sdk-msbuild-vs.md
|
||||||
| - Visual Studio 18.0 and .NET 10.0.1xx | ||||||
|
Check failure on line 119 in docs/core/porting/versioning-sdk-msbuild-vs.md
|
||||||
| - **Backward compatibility**: Using the latest feature band of the previous SDK version (for example, 8.0.4xx in Visual Studio 17.14) is supported with best-effort compatibility. We'll determine when to backport fixes based on risk and customer impact. | ||||||
|
Check failure on line 120 in docs/core/porting/versioning-sdk-msbuild-vs.md
|
||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| While older SDKs than the latest of the prior band may work, we will not test them or make an effor to ensure any compatibility. | ||||||
|
There was a problem hiding this comment. Typo: "effor" should be "effort".
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| - **Forward compatibility**: Using a newer SDK (for example, .NET 10 SDK in Visual Studio 17.14) is allowed without blocking, but targeting newer runtimes in older Visual Studio versions is not supported and should provide a build warning. | ||||||
|
Comment on lines
+120
to
+122
There was a problem hiding this comment. The sentence "While older SDKs…" looks like it's intended as part of the "Backward compatibility" list item, but it isn't indented, so it renders as a separate paragraph outside the list. Indent it to be part of that bullet (or convert it into a nested bullet) for correct markdown structure.
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ### Guidance | ||||||
|
|
||||||
| Our guidance is to use the SDK that came with your Visual Studio instance (or latest available in CI or Visual Studio Code) as that will always have newest features including security updates. | ||||||
gewarren marked this conversation as resolved.
Show resolved
Hide resolved
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ## Downlevel targeting support | ||||||
|
There was a problem hiding this comment. The heading uses "Downlevel", but earlier in the article you use "down-level" (for example, "down-level versions" in the note above). Pick one form and use it consistently (usually "down-level"). |
||||||
|
|
||||||
| The .NET SDK maintains targeting support for out-of-support .NET versions. The 10.0.100 SDK can build apps targeting `net9.0` all the way down to `netcoreapp1.0`. | ||||||
|
|
||||||
| ### Guiding principles | ||||||
|
|
||||||
| - **Existing support preserved**: Targeting support for out-of-support versions remains in the SDK without active removal. Customers upgrading their SDK or Visual Studio version should not have their builds broken simply by targeting an older .NET version. | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| - **New features**: New SDK features aren't required to support out-of-support versions unless excluding such support poses considerable cost or risk. | ||||||
| - **Breakage fixes**: If issues arise when targeting out-of-support versions, a fix is applied based on the cost of the fix. The goal is to prevent customers from being broken on upgrade. | ||||||
|
|
||||||
| ## Preview versioning | ||||||
|
|
||||||
| 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 | | ||||||
| |---------------------|-----------------------| | ||||||
| | 10.0.100 RC 1 | 18.0.0 Insiders (11010.61)| | ||||||
| | 10.0.100 RC 2 | 18.0.0 Insiders (11111.16)| | ||||||
| | 11.0.100 Preview 1 | 18.4.0 Insiders 1 | | ||||||
|
There was a problem hiding this comment. The new preview row's Visual Studio version format doesn't match the rows above (those include an "Insiders" build number in parentheses). Align the formatting so readers can compare versions consistently.
Suggested change
|
||||||
|
|
||||||
| ## Reference | ||||||
|
|
||||||
|
|
||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.