This article explains the policies used by the .NET tools, SDK, and runtime for selecting versions. These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. These policies enable:

• Easy and efficient deployment of .NET, including security and reliability updates.
• Use the latest tools and commands independent of target runtime.

Version selection occurs:

• When you run an SDK command,the SDK uses the latest installed version.
• When you build an assembly,target framework monikers define build time APIs.
• When you run a .NET application,target framework dependent apps roll-forward.
• When you publish a self-contained application,self-contained deployments include the selected runtime.

The rest of this document examines those four scenarios.

The SDK uses the latest installed version

SDK commands includedotnet new anddotnet run. The .NET CLI must choose an SDK version for everydotnet command. It uses the latest SDK installed on the machine by default, even if:

• The project targets an earlier version of the .NET runtime.
• The latest version of the .NET SDK is a preview version.

You can take advantage of the latest SDK features and improvements while targeting earlier .NET runtime versions. You can target different runtime versions of .NET using the same SDK tools.

In some circumstances, you might need to use a specific version of the SDK. You specify that version in aglobal.json file.

global.json can be placed anywhere in the file hierarchy. You control which projects a givenglobal.json applies to by its place in the file system. The .NET CLI searches for aglobal.json file iteratively navigating the path upward from the current working directory (which isn't necessarily the same as the project directory). The firstglobal.json file found specifies the version used. If that SDK version is installed, that version is used. If the SDK specified in theglobal.json isn't found, the .NET CLI usesmatching rules to select a compatible SDK, or fails if none is found.

The following example shows theglobal.json syntax:

{  "sdk": {    "version": "5.0.0"  }}

The process for selecting an SDK version is:

1. dotnet searches for aglobal.json file iteratively reverse-navigating the path upward from the current working directory.
2. dotnet uses the SDK specified in the firstglobal.json found.
3. dotnet uses the latest installed SDK if noglobal.json is found.

For more information about SDK version selection, see theMatching rules androllForward sections of theglobal.json overview article.

Updating the SDK version

It's important to update to the latest version of the SDK regularly to adopt the latest features, performance improvements, and bug fixes. To easily check for updates to the SDK, use thedotnet sdk checkcommand. Additionally, if you select a specific version usingglobal.json, consider a tool such as Dependabot to automatically update the pinned SDK version as new versions become available.

Target framework monikers define build time APIs

You build your project against APIs defined in atarget framework moniker (TFM). You specify thetarget framework in the project file. Set theTargetFramework element in your project file as shown in the following example:

<TargetFramework>net8.0</TargetFramework>

You can build your project against multiple TFMs. Setting multiple target frameworks is more common for libraries but can be done with applications as well. You specify aTargetFrameworks property (plural ofTargetFramework). The target frameworks are semicolon-delimited as shown in the following example:

<TargetFrameworks>net8.0;net47</TargetFrameworks>

A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. For example, the .NET 8 SDK includes the .NET 8 runtime, which is an implementation of thenet8.0 target framework. The .NET 8 SDK supportsnet7.0,net6.0, andnet5.0, but notnet9.0 (or higher). You install the .NET 9 SDK to build fornet9.0.

.NET Standard

.NET Standard was a way to target an API surface shared by different implementations of .NET. Starting with the release of .NET 5, which is an API standard itself, .NET Standard has little relevance, except for one scenario: .NET Standard is useful when you want to target both .NET and .NET Framework. .NET 5 implements all .NET Standard versions.

For more information, see.NET 5 and .NET Standard.

Framework-dependent apps roll-forward

When you run an application from source withdotnet run, from aframework-dependent deployment withdotnet myapp.dll, or from aframework-dependent executable withmyapp.exe, thedotnet executable is thehost for the application.

The host chooses the latest patch version installed on the machine. For example, if you specifiednet5.0 in your project file, and5.0.2 is the latest .NET runtime installed, the5.0.2 runtime is used.

If no acceptable5.0.* version is found, a new5.* version is used. For example, if you specifiednet5.0 and only5.1.0 is installed, the application runs using the5.1.0 runtime. This behavior is referred to as "minor version roll-forward." Lower versions also won't be considered. When no acceptable runtime is installed, the application doesn't run.

A few usage examples demonstrate the behavior, if you target 5.0:

• ✔️ 5.0 is specified. 5.0.3 is the highest patch version installed. 5.0.3 is used.
• ❌ 5.0 is specified. No 5.0.* versions are installed. 3.1.1 is the highest runtime installed. An error message is displayed.
• ✔️ 5.0 is specified. No 5.0.* versions are installed. 5.1.0 is the highest runtime version installed. 5.1.0 is used.
• ❌ 3.0 is specified. No 3.x versions are installed. 5.0.0 is the highest runtime installed. An error message is displayed.

Minor version roll-forward has one side-effect that might affect end users. Consider the following scenario:

1. The application specifies that 5.0 is required.
2. When run, version 5.0.* isn't installed, however, 5.1.0 is. Version 5.1.0 is used.
3. Later, the user installs 5.0.3 and runs the application again, 5.0.3 is now used.

It's possible that 5.0.3 and 5.1.0 behave differently, particularly for scenarios like serializing binary data.

Control roll-forward behavior

Before overriding default roll-forward behavior, familiarize yourself with the level of.NET runtime compatibility.

The roll-forward behavior for an application can be configured in four different ways:

1. Project-level setting by setting the<RollForward> property:

   <PropertyGroup>  <RollForward>LatestMinor</RollForward></PropertyGroup>

2. The*.runtimeconfig.json file.

   This file is produced when you compile your application. If the<RollForward> property was set in the project, it's reproduced in the*.runtimeconfig.json file as therollForward setting. Users can edit this file to change the behavior of your application.

   {  "runtimeOptions": {    "tfm": "net5.0",    "rollForward": "LatestMinor",    "framework": {      "name": "Microsoft.NETCore.App",      "version": "5.0.0"    }  }}

3. Thedotnet command's--roll-forward <value> property.

   When you run an application, you can control the roll-forward behavior through the command line:

   dotnet run --roll-forward LatestMinordotnet myapp.dll --roll-forward LatestMinormyapp.exe --roll-forward LatestMinor

4. TheDOTNET_ROLL_FORWARD environment variable.

Precedence

Roll forward behavior is set by the following order when your app is run, higher numbered items taking precedence over lower numbered items:

1. First the*.runtimeconfig.json config file is evaluated.
2. Next, theDOTNET_ROLL_FORWARD environment variable is considered, overriding the previous check.
3. Finally, any--roll-forward parameter passed to the running application overrides everything else.

Values

However you set the roll-forward setting, use one of the following values to set the behavior:

For example, suppose an application requests version8.0.0, while the locally available versions are8.2.0,8.2.3,8.4.5,9.0.0,9.0.6,9.7.8.Then the resolved version is as follows in each case:

Self-contained deployments include the selected runtime

You can publish an application as aself-contained distribution. This approach bundles the .NET runtime and libraries with your application. Self-contained deployments don't have a dependency on runtime environments. Runtime version selection occurs at publishing time, not run time.

Therestore event that occurs when publishing selects the latest patch version of the given runtime family. For example,dotnet publish selects .NET 5.0.3 if it's the latest patch version in the .NET 5 runtime family. The target framework (including the latest installed security patches) is packaged with the application.

An error occurs if the minimum version specified for an application isn't satisfied.dotnet publish binds to the latest runtime patch version (within a given major.minor version family).dotnet publish doesn't support the roll-forward semantics ofdotnet run. For more information about patches and self-contained deployments, see the article onruntime patch selection in deploying .NET applications.

Self-contained deployments might require a specific patch version. You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example:

<PropertyGroup>  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion></PropertyGroup>

TheRuntimeFrameworkVersion element overrides the default version policy. For self-contained deployments, theRuntimeFrameworkVersion specifies theexact runtime framework version. For framework-dependent applications, theRuntimeFrameworkVersion specifies theminimum required runtime framework version.

See also

• Dependabot supported ecosystems and repositories.
• Download and install .NET.
• How to check that .NET is already installed.
• How to remove the .NET Runtime and SDK.