.NET SDK, MSBuild, and Visual Studio versioning - .NET Core (original) (raw)

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 .NET SDK version number uses the format major.minor.patch, where:

• major.minor matches the .NET version the SDK includes, runs on, and targets by default.
• The hundreds digit of patch identifies the _feature band_—for example, 1xx, 2xx, 3xx, or 4xx. The feature band starts at 1 and increases for each quarterly .NET SDK release.
• The last two digits of patch are the patch version, which increments with each month's servicing update.

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, and Visual Studio upgrade won't touch that version. You're responsible for updating that copy of the .NET SDK from then on.

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.

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.

Lifecycle

The support timeframe for the SDK typically matches that of the Visual Studio version it's included in.

Expand to see out-of-support .NET versions

Supported .NET versions

Note

1 .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.

2 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

Visual Studio 2022 lifecycle

Visual Studio 2019 lifecycle

Targeting and support rules

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.
• The first version of a new .NET SDK that supports a new TargetFramework can still be used with the prior version of Visual Studio to allow one quarter for tooling and infrastructure (for example, actions and pipelines) to migrate.

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.

Targeting net8.0 is officially supported in Visual Studio 17.8+ only.

Targeting net9.0 is officially supported in Visual Studio 17.12+ only.

Targeting net10.0 is officially supported in Visual Studio 18.0+ only.

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. There is no guarantee every Visual Studio version works with every in-support .NET SDK. The most common configurations are tested to ensure a best effort of compatibility.

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
  • 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. The .NET team determines when to backport fixes based on risk and customer impact. While SDKs that are older than the latest of the prior band might work, the .NET team does not test them or make an effort 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 isn't supported and produces a build warning.

Guidance

Use the SDK that came with your Visual Studio instance (or latest available in CI or Visual Studio Code), as that version always has the newest features, including security updates.

Down-level targeting support

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 that upgrade their SDK or Visual Studio version should not have their builds broken simply by targeting an older .NET version.
• 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.

Reference

• Overview of how .NET is versioned
• .NET and .NET Core official support policy
• Microsoft .NET and .NET Core
• .NET Downloads (Windows, Linux, and macOS)
• Visual Studio 2019 Product Lifecycle and Servicing