|
| 1 | +--- |
| 2 | +title: .NET Core version selection |
| 3 | +description: Learn how .NET Core finds and chooses runtime versions for your program. |
| 4 | +author: billwagner |
| 5 | +ms.author: wiwagn |
| 6 | +ms.date: 06/27/2018 |
| 7 | +--- |
| 8 | +# .NET Core version selection |
| 9 | + |
| 10 | +[!INCLUDE [topic-appliesto-net-core-2plus](../../../includes/topic-appliesto-net-core-2plus.md)] |
| 11 | + |
| 12 | +This article explains the policies used by the .NET Core 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 perform the following: |
| 13 | + |
| 14 | +- Easy and efficient deployment of .NET Core, including security and reliability updates. |
| 15 | +- Use the latest tools and commands independent of target runtime. |
| 16 | + |
| 17 | +Version selection occurs: |
| 18 | + |
| 19 | +- When you run an SDK command, [the sdk uses the latest installed version](#the-sdk-uses-the-latest-installed-version). |
| 20 | +- When you build an assembly, [target framework monikers define build time APIs](#target-framework-monikers-define-build-time-apis). |
| 21 | +- When you run a .NET Core application, [target framework dependent apps roll forward](#framework-dependent-apps-roll-forward). |
| 22 | +- When you publish a self-contained application, [self-contained deployments include the selected runtime](#self-contained-deployments-include-the-selected-runtime). |
| 23 | + |
| 24 | +The rest of this document examines those four scenarios. |
| 25 | + |
| 26 | +## The SDK uses the latest installed version |
| 27 | + |
| 28 | +SDK commands include `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` CLI must choose an SDK version for any command. The .NET Core CLI uses the latest SDK installed on the machine by default. You'll use the .NET Core SDK v2.1.301 when it's installed, even if the project you are working with targets the .NET Core Runtime 2.0. Note that this is true for preview versions as well as released versions. You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects. |
| 29 | + |
| 30 | +On rare occasions, you may need to use an earlier version of the SDK. You specify that version in a [*global.json* file](../tools/global-json.md). The "use latest" policy means you only use *global.json* to specify a .NET Core version earlier than the latest installed version. |
| 31 | + |
| 32 | +*global.json* can be placed anywhere in the file hierarchy. The CLI searches upward from the project directory for the first *global.json* it finds. You control which projects a given *global.json* applies to by its place in the file system. The .NET CLI searches for a *global.json* file iteratively navigating the path upward from the current working directory. The first *global.json* file found specifies the version used. If that version is installed, that version is used. If the SDK specified in the *global.json* is not found, the .NET CLI rolls forward to the latest SDK installed. This is the same as the default behavior, when no *global.json** file is found. |
| 33 | + |
| 34 | +The following example shows the *global.json* syntax: |
| 35 | + |
| 36 | +``` json |
| 37 | +{ |
| 38 | + "sdk": { |
| 39 | + "version": "2.0.0" |
| 40 | + } |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +The process for selecting an SDK version is: |
| 45 | + |
| 46 | +1. `dotnet` searches for a *global.json* file iteratively reverse-navigating the path upward from the current working directory. |
| 47 | +1. `dotnet` uses the SDK specified in the first *global.json* found. |
| 48 | +1. `dotnet` binds to the latest installed SDK if no *global.json* is found. |
| 49 | + |
| 50 | +You can learn more about selecting an SDK version in the [matching rules](../tools/global-json.md) section of the topic on *global.json*. |
| 51 | + |
| 52 | +## Target Framework Monikers define build time APIs |
| 53 | + |
| 54 | +You build your project against APIs defined in a **Target Framework Moniker** (TFM). You specify the [target framework](../../standard/frameworks.md) in the project file. Set the `TargetFramework` element in your project file as shown in the following example: |
| 55 | + |
| 56 | +``` xml |
| 57 | +<TargetFramework>netcoreapp2.0</TargetFramework> |
| 58 | +``` |
| 59 | + |
| 60 | +You may 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 a `TargetFrameworks` property (plural of `TargetFramework`). The target frameworks are semicolon-delimited as shown in the following example: |
| 61 | + |
| 62 | +``` xml |
| 63 | +<TargetFrameworks>netcoreapp2.0;net47</TargetFrameworks> |
| 64 | +``` |
| 65 | + |
| 66 | +A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. For example, the .NET Core 2.0 SDK includes the .NET Core 2.0 runtime, which is an implementation of the `netcoreapp2.0` target framework. The .NET Core 2.0 SDK supports `netcoreapp1.0`, `netcoreapp1.1`, and `netcoreapp2.0` but not `netcoreapp2.1` (or higher). You install the .NET Core 2.1 SDK to build for `netcoreapp2.1`. |
| 67 | + |
| 68 | +.NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. The .NET Core 2.0 SDK is capped to `netstandard2.0`. |
| 69 | + |
| 70 | +## Framework-dependent apps roll forward |
| 71 | + |
| 72 | +You run an application from source with [`dotnet run`](../tools/dotnet-run.md). `dotnet run` both builds and runs an application. The `dotnet` executable is the **host** for the application in development environments. |
| 73 | + |
| 74 | +The host chooses the latest patch version installed on the machine. For example, if you specified `netcoreapp2.0` in your project file, and `2.0.4` is the latest .NET runtime installed, the `2.0.4` runtime is used. |
| 75 | + |
| 76 | +If no acceptable `2.0.*` version is found, a new `2.*` version is used. For example, if you specified `netcoreapp2.0` and only `2.1.0` is installed, the application runs using the `2.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 won't run. |
| 77 | + |
| 78 | +A few usage examples demonstrate the behavior: |
| 79 | + |
| 80 | +- 2.0.4 is required. 2.0.5 is the highest patch version installed. 2.0.5 is used. |
| 81 | +- 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is displayed. |
| 82 | +- 2.04 is required. 2.0.0 is the latest version installed. An error message is displayed. |
| 83 | +- 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is the highest 2.x runtime version installed. 2.2.2 is used. |
| 84 | +- 2.0.4 is required. No 2.x versions are installed. 3.0.0 (not a currently available version) is installed. An error message is displayed. |
| 85 | + |
| 86 | +Minor version roll-forward has one side-effect that may affect end users. Consider the following scenario: |
| 87 | + |
| 88 | +- 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is installed. 2.2.2 is used. |
| 89 | +- 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. The latest patch is preferred over an updated minor version. |
| 90 | +- It's possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. |
| 91 | + |
| 92 | +## Self-contained deployments include the selected runtime |
| 93 | + |
| 94 | +You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach bundles the .NET Core 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. |
| 95 | + |
| 96 | +The publishing process selects the latest patch version of the given runtime family. For example, `dotnet publish` will select .NET Core 2.0.4 if it is the latest patch version in the .NET Core 2.0 runtime family. The target framework (including the latest installed security patches) are packaged with the application. |
| 97 | + |
| 98 | +It's an error 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 of `dotnet run`. For more information about patches and self-contained deployments, see the article on [runtime patch selection](../deploying/runtime-patch-selection.md) in deploying .NET Core applications. |
| 99 | + |
| 100 | +Self-contained deployments may 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: |
| 101 | + |
| 102 | +``` xml |
| 103 | +<RuntimeFrameworkVersion>2.0.4</RuntimeFrameworkVersion> |
| 104 | +``` |
| 105 | + |
| 106 | +The `RuntimeFrameworkVersion` element overrides the default version policy. For self-contained deployments, the `RuntimeFrameworkVersion` specifies the *exact* runtime framework version. For framework dependent applications, the `RuntimeFrameworkVersion` specifies the *minimum* patch level of the framework. |
0 commit comments