Skip to content

Update SDK documentation #26329

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 1, 2021
Merged

Update SDK documentation #26329

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1f381af
Update SDK documentation
marcpopMSFT Sep 30, 2021
a27cad9
Apply suggestions from code review
marcpopMSFT Oct 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 21 additions & 25 deletions docs/core/porting/versioning-sdk-msbuild-vs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,43 +7,39 @@ ms.date: 06/10/2021
---
# Overview of .NET, MSBuild, and Visual Studio versioning

Understanding the versioning of the SDK and how it relates to Visual Studio and MSBuild can frequently be confusing. MSBuild versions with VS but is also included in the SDK. The SDK has a minimum version of MSBuild that it works with and it won't load in a VS that is older than it supports.
Understanding the versioning of the .NET SDK and how it relates to Visual Studio and MSBuild can be confusing. MSBuild versions with Visual Studio, but is also included in the .NET SDK. The SDK has a minimum version of MSBuild and Visual Studio that it works with, and it won't load in a version of Visual Studio that's older than that minimum version.

## Versioning

The first part of the SDK matches the .NET version that it includes, runs on, and targets by default. The feature band starts at 1 and increases for each quarterly VS minor release. The patch version increments with each month's servicing updates.
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 Visual Studio minor release. The patch version increments with each month's servicing updates.

For example, 5.0.203 ships with .NET 5.0, is the second minor VS release since 5.0.100 first came out, and is the third patch since 5.0.200 released.
For example, version 5.0.203 ships with .NET 5.0, is the second minor Visual Studio release since 5.0.100 first came out, and is the third patch since 5.0.200 released.

## Lifecycle

The support timeframe for the SDK typically matches the VS it's included in.

| SDK Version | MSBuild/VS version | Minimum required MSBuild/VS Version | Ship date | Lifecycle |
|------------------|--------------------|-------------------------------------|--------------|-----------|
| 2.1.5xx | 15.9 | 15.3 | Nov '18 | Aug '21* |
| 2.1.8xx | 16.2 (No VS) | 16.0 | July '19 | Aug '21 |
| 3.1.1xx | 16.4 | 16.3 | Dec '19 | Dec '22 |
| 3.1.4xx | 16.7 | 16.7 | Aug '20 | Dec '22 |
| 5.0.1xx | 16.8 | 16.8 | November '20 | Mar '21 |
| 5.0.2xx | 16.9 | 16.8 | March '21 | Aug '22 |
| 5.0.3xx | 16.10 | 16.8 | May '21 | Aug '21 |
| 5.0.4xx | 16.11 | 16.8 | Aug '21 | Feb '22* |
| 6.0.100-preview4 | 16.10 (No VS) | 16.10-preview3 | May '21 | N/A |
| 6.0.100-preview5 | 17.0-preview 1 | 16.10 | June '21 | N/A |
| 6.0.100-preview6 | 17.0-preview 2 | 16.10 | July | N/A |
| 6.0.100-preview7 | 17.0-preview 3 | 16.10 | August | N/A |
| 6.0.100-rc1 | 17.0-preview 4 | 16.10 | September | N/A |
| 6.0.100 | 17.0 | 16.10** | Nov. '21 | |
The support timeframe for the SDK typically matches that of the Visual Studio version it's included in.

| SDK Version | MSBuild/VS version | Ship date | Lifecycle |
|------------------|--------------------|--------------|-----------|
| 2.1.5xx | 15.9 | Nov '18 | Aug '21* |
| 2.1.8xx | 16.2 (No VS) | July '19 | Aug '21 |
| 3.1.1xx | 16.4 | Dec '19 | Dec '22 |
| 3.1.4xx | 16.7 | Aug '20 | Dec '22 |
| 5.0.1xx | 16.8 | November '20 | Mar '21 |
| 5.0.2xx | 16.9 | March '21 | Aug '22 |
| 5.0.3xx | 16.10 | May '21 | Aug '21 |
| 5.0.4xx | 16.11 | Aug '21 | Feb '22* |
| 6.0.100-rc1 | 17.0-preview 4 | September | N/A |
| 6.0.100 | 17.0** | Nov. '21 | |

> [!NOTE]
> The Minimum version is what's required to load the SDK but doesn't cover what's supported. Targeting net6.0 is officially supported in 17.0+ only.
> Targeting `net6.0` is officially supported in Visual Studio 17.0+ only.

> \* MSbuild/VS supported for longer
> \* MSbuild/Visual Studio supported for longer
>
> \*\* You won't have to upgrade to 17.0 on the day .NET 6 releases. This is the current version and will likely be 16.11 at release. This version supports downlevel targeting, such as .NET 5 and below, but doesn't allow targeting .NET 6 for the purpose of using .NET 6 or C# 10 features.
> \*\* When .NET 6 releases, the goal is for the .NET SDK to be functional in version 16.11 for **downlevel** targeting. This means that you're not forced to update your SDK and Visual Studio versions simultaneously. However, you won't be able to target .NET 6 because of limitations in 6.0 features and C#10 features in version 16.11. This compatibility is specifically for targeting 5.0 and below.

Expect breaking changes that require a new MSBuild and VS version at least once a year, for each major SDK release. There shouldn't be breaking changes in SDK feature (patch) updates.
Expect breaking changes that require a new MSBuild and Visual Studio version at least once a year, for each major SDK release. All versions of 5.0.Nxx SDK will load on all versions of Visual Studio and MSBuild from 16.8 - 16.11, as no breaking changes were made during that time. There shouldn't be breaking changes in SDK feature (patch) updates.

## Reference

Expand Down