Update SDK versioning document to include support matrix guidance #51412
Conversation
There was a problem hiding this comment.
Pull request overview
Updates the .NET SDK/MSBuild/Visual Studio versioning article to clarify how SDK feature bands relate to Visual Studio releases, and to document expected support for common mismatched SDK/Visual Studio configurations.
Changes:
- Updates the “Versioning” section to describe feature bands as quarterly .NET SDK releases, and adds guidance about Visual Studio’s newer monthly minor release cadence.
- Extends the lifecycle and compatibility tables to include .NET SDK
10.0.2xx, and adds a .NET 11 preview entry. - Adds an “SDK and Visual Studio support matrix” section describing primary, backward, and forward compatibility expectations.
| | 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 | | ||
| | 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.
| 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. | ||
|
|
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 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. | ||
| 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. | ||
| - **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. |
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.
| - Visual Studio 17.14 and .NET 9.0.3xx | ||
| - Visual Studio 18.0 and .NET 10.0.1xx | ||
| - **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. | ||
| 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".
|
|
||
| ### 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. |
There was a problem hiding this comment.
"Our guidance" reintroduces first-person voice, and the sentence is missing an article ("the newest features"). Rephrase in second person/imperative voice and fix the grammar so the recommendation reads clearly.
|
|
||
| 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. | ||
|
|
||
| ## 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").
| | 10.0.100 Preview 3 | 17.14 Preview 3 | | ||
| | 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.
| | 11.0.100 Preview 1 | 18.4.0 Insiders 1 | | |
| | 11.0.100 Preview 1 | 18.4.0 Insiders (1) | |
|
|
||
| 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).
| 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. | |
| Starting with Visual Studio 18.0, Visual Studio ships monthly minor versions, while the .NET SDK continues to ship quarterly. Visual Studio releases between quarterly .NET SDK releases contain only patch versions of the latest .NET SDK. |
Summary
There is often questions about what do we support when mismatching the .NET SDK and Visual Studio. This update tries to clarify what we test and what we'll fix in those situations.
Additionally, I added 10.0.2xx and 11.0.1xx-preview1 as well as details on the new Visual Studio release mode.
Internal previews