From 09e3ff6e7cb5cbbec8f5c45df1a0c8930835cf03 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 20 Jun 2018 15:04:56 -0400 Subject: [PATCH 01/13] initial commit Original design doc. Updated TOC Add paragraph in overview topic --- docs/core/versions/binding.md | 264 ++++++++++++++++++++++++++++++++++ docs/core/versions/index.md | 10 ++ docs/toc.md | 5 + 3 files changed, 279 insertions(+) create mode 100644 docs/core/versions/binding.md diff --git a/docs/core/versions/binding.md b/docs/core/versions/binding.md new file mode 100644 index 0000000000000..15ef25e058311 --- /dev/null +++ b/docs/core/versions/binding.md @@ -0,0 +1,264 @@ +# .NET Core 2+ Version Binding + +.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are defined in this document. + +One can think of these policies performing the following roles: + +- Providing an implicit "version manager" experience. +- Enabling easy and efficient deployment of .NET Core, including security and reliability updates. +- Enabling developers to use the latest tools and commands independent of target runtime. + +## Experience + +.NET Core provides a single entry-point for operating on projects and built applications, specifically with the `dotnet` command. This experience relies on an installation structure that can include multiple runtime and SDK versions. This structure is machine global and in the path by default, enabling a developer to access all .NET Core versions from any command prompt. It also enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. This differs from other development platforms that require re-setting the path or setting an environmental value to use different platform versions. + +There is allowance for other scenarios, for example, for private .NET Core installations without use of the path. This document focusses more on the default behavior, but does call out opportunities to override this behavior. + +The `dotnet` command must select a version in the following cases: + +- Select an SDK to use to run an SDK command (for example, with `dotnet new`). +- Select a runtime to target an application (for example, with `dotnet build`). +- Select a runtime to run an application (for example, with `dotnet run`). +- Select a runtime to publish an application (with `dotnet publish`). + +## Selecting an SDK + +The first developer experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must select a version of the SDK to use to satisfy these commands. .NET Core has a "use the latest SDK" policy. This means that you will use the .NET Core 99.9 SDK if you install it on a machine, even if you are using the SDK command to do .NET Core 2.0 development. + +The advantage of this policy is that you can take advantage of the latest SDK features and improvements while continuing to target earlier .NET Core versions. This is logically similar to using C# 7 with .NET Framework 4.5 (which also works). It is quite likely many developers will target multiple versions of .NET Core across a set of projects. It's nice that you can use the same tools for all of them. + +You can configure `dotnet` to use a different version of the SDK by specifying that version in a [global.json file](https://docs.microsoft.com/dotnet/articles/core/tools/global-json). As a consequence of the "use latest" policy, you would only ever use `global.json` to specify a .NET Core version that is earlier than the latest installed version. + +You can use `global.json` at a variety of scopes: + +- Per project, placed beside the project file. +- For a set of projects, placed at a common [grand-]parent for all of the projects. This location can be as high in the directory structure as the root of a drive. + +You can see the `global.json` syntax in the following example: + +``` json +{ + "sdk": { + "version": "1.0.0" + } +} +``` + +The `global.json` file is an existing format and associated concept that is part of the .NET Core 1.0 tools. It is not new with .NET Core 2.0. The file fulfills a critical role, to enable developers to lock a specific app or set of apps to an earlier SDK than the latest on the machine. The need for this capability is most obvious for developers that need to continue using the preview2 sdk to use project.json-based applications. We will revisit the design of this file in a later release. We will also want to understand how often it is even used to better understand how important the scenario is. The less it is used, the more likely the file will stay as-is. + +Implementer notes: + +- `dotnet` binds to latest SDK by default. +- This behavior can be overridden by global.json. +- The first global.json file found is selected, iteratively reverse-navigating the path from the current working directory. + +## Building an application + +You can build an application from source with `dotnet build` or `dotnet run` (the latter does more than is covered in this section). + +There are multiple points of version binding to consider: + +- Selecting an SDK. +- Defining the target framework for the application. +- Defining a minimum runtime version. + +The process of selecting an SDK is described earlier in the document. + +The target framework is defined in the project file by setting a property in the following form: + +``` xml +netcoreapp2.0 +``` + +Multiple target frameworks can also be set if you need to build different code for different targets. This scenario is more common for libraries, but can be done with applications as well. You can do this by using a `TargetFrameworks` property (plural of TargetFramework). The target frameworks will be semicolon-delimited as you can see the following example: + +``` xml +netcoreapp2.0;net47 +``` + +A given SDK will support a fixed set of frameworks, typically capped to the target framework of the runtime(s) it includes. 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 will support `netcoreapp1.0`, `netcoreapp1.1` and `netcoreapp2.0` but not `netcoreapp2.1` (or higher). You will need to install the .NET Core 2.1 SDK in order to build for `netcoreapp2.1`. + +.NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK will be capped to `netstandard2.0`. + +A given SDK will define a fixed minimum runtime patch version for each target framework that it supports. The minimum runtime patch version will be maintained at the `.0` version (for example, `2.0.0`) for the lifetime of a major/minor runtime version family. This policy makes deploying patches a web hoster concern and not a developer concern. + +Hosters and other users have reported challenges with the .NET Core 1.x behavior, where the minimum patch version increases with each .NET Core SDK release. See: [Reconsider implicitly using the latest patch version of the targeted version of .NET Core in the SDK](https://github.com/dotnet/sdk/issues/983). This proposal is intended to resolve their feedback. + +The SDK stores the minimum patch version for each supported target framework in the `~\dotnet\sdk\1.0.0\Sdks\Microsoft.NET.Sdk\build\Microsoft.NET.Sdk.DefaultItems.targets` file. + +The minimum runtime patch version is stored in the application directory in the `*.runtimeconfig.json` file. This value is used as part of runtime selection. You are not intended to edit this file. + +You can override the minimum runtime patch version (to higher or lower versions) in the project file, as you can see in the following example: + +``` xml +2.0.4 +``` + +In the case that you target multiple target frameworks, you need to condition the minimum runtime patch version to the specific .NET Core target framework, as you can see in the following example: + +``` xml +netcoreapp2.0;net47 +2.0.4 +``` + +Implementer notes: + +- A given SDK supports a fixed set of target frameworks. +- It is an error to target a framework outside that set. +- The SDK defines the minimum runtime patch version (set at the .0 patch) for a given target framework. +- This version can be overridden in a project file. + +## Run from Source with dotnet run + +You can run an application from source with `dotnet run`. `dotnet run` both builds and runs an application. + +There are multiple points of version binding to consider: + +- Selecting an SDK +- Defining a target framework for the appliction +- Defining a minimum runtime patch version +- Selecting a runtime to run on + +The process of selecting an SDK and building an application is described earlier in the document. + +The built application will be run on machines that satisfy the minimum required runtime patch version, stored in the `*.runtimeconfig.json` file. The highest patch version will be selected. For example, the `2.0.4` runtime will be selected in the case that the minimum runtime version is `2.0.0` while `2.0.0`, `2.0.1` and `2.0.4` are all resident on the machine. Higher minor or major versions (for example, `2.1.1` or `3.0.1`) will not be considered. Lower versions will also not be considered. + +Implementer notes: + +- It is an error if the minimum version specified for an application is not satisfied. +- `dotnet` binds to latest runtime patch version (within a given major.minor version family). + +## Run from bin directory with dotnet myapp.dll + +You can build and then run an application, essentially performing `dotnet run` as two separate steps, as seen in the following example: + +``` console +dotnet build +dotnet bin\Debug\netcorapp2.0\myapp.dll +``` + +This scenario is an equivalence class for `dotnet run`. + +## Run a published application with dotnet myapp.dll + +You can publish an application to prepare it for distribution to other runtime environments, as seen in the following example: + +``` console +dotnet publish -c release -o app +dotnet .\app\app.dll +``` + +This scenario is an equivalence class for `dotnet run`. + +## Run a published application with the required runtime missing + +You may run an application on a machine that is missing the runtime required by the application. If the required runtime is missing and a higher minor version is installed, the minor version should be used instead of failing to load the application. Higher major versions will not be used to load applications. This behavior shall be called "minor version roll-forward." + +To illustrate this behavior, for an application requiring 2.0.4, `dotnet` would search and bind to a runtime in this order (picking the first it finds or showing error): + +- 2.0.* (highest patch version; ensure that it satisfies 2.0.4 as a lower bound) +- 2.* (highest minor version) +- A helpful error message appears (see the message that follows) + +> This application requires .NET Core 2.0.4. Please install .NET Core 2.0.4 or a higher compatible version. +> Please see https://aka.ms/install-dotnet-core to learn about .NET Core installation and runtime versioning. + +A few usage examples may help to demonstrate the desired behavior: + +- 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. +- 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error with a helpful error message is printed. +- 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. +- 2.0.4 is required. No 2.x versions are installed. 3.0.0 is installed. An error with a helpful error message is printed. + +There is a trade-off for this behavior between compatibility and convenience. .NET Core minor versions are intended to be very compatible. It is therefore reasonable to choose the convenience experience without significant concern for compatibility breaks. + +The following example is a somewhat unfortunate side-effect behavior of the algorithm that is important to realize: + +- 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is installed. It is used. +- 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. +- It is possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. + +The treatment of NuGet dependencies needs to be understood as well. A given application might be built for .NET Core 2.0 but run on .NET Core 2.1 due to this algorithm. There may be later versions of an application's NuGet dependencies that target .NET Core 2.1. These later versions will not be considered or consulted. All NuGet dependencies should be already resolved as part of the published application layout, residing as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. + +There are some scenarios where ASP.NET packages will be deployed via a web host rather than with a published application. In those cases, it is recommended that web hosters correctly configure their environments based on published guidance such that all supported ASP.NET applications run correctly. + +Implementer notes: + +- Runtimes are searched for in the following order (the first found is loaded): + - Highest patch version (check that the minimum runtime path version is satisfied, otherwise error) + - Highest minor version +- If an acceptable runtime is not found, then error. + +## Publish a self-contained application + +You can publish an application as a self-contained distribution. The advantage of this approach is that it includes .NET Core so does not require it is a dependency in runtime environments. As a result, runtime binding occurs at publishing time not run-time. + +There are multiple points of version binding to consider: + +- Selecting an SDK +- Defining a target framework for the application +- Selecting a runtime to publish + +The process of selecting an SDK and building an application is described earlier in the document. + +The publishing process will select 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, independent of the existence of earlier patch versions or minimum runtime patch version values. This differs from `dotnet build` runtime selection for two reasons: + +- The application doesn't need to align with a hosting environment. +- The developer is generating a final configuration for the application (that cannot be practically modified). The best runtime choice is the latest installed runtime patch version, both because that is the same version as was used for development and because it will have the latest (per the machine) security and reliability fixes. + +Note that the runtimeframeworkversion element will override the default version policy if that element is present in the project file. + +Implementer Notes: + +- It is an error if the minimum version specified for an application is not satisfied. +- `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). +- `dotnet publish` does not support the roll-forward semantics of `dotnet run` + +## Publish an application with a specific .NET Core version + +Developers can specify a .NET Core runtime version within a project file. That's convenient for developers because they typically work on one project at a time and typically edit project files, but not for CI/CD flows or human software deployers who manage many projects and who do not typically edit project files. Instead `dotnet publish` accepts a version to use for publishing for both self-contained and framework-dependent apps. One can imagine Visual Studio Team Systems offering a setting to specify a runtime version within a build configuration UI that affects publish without needing to update source code. + +You can publish with the latest runtime patch version for the given target framework, by specifying `--latest`. This argument has the same default runtime binding behavior for publishing self-contained applications. You can see this usage in the following example: + +``` console +dotnet publish -c release -o app --latest +``` + +You can publish with a specific runtime patch version for the given target framework, by specifying `--version=[version]`. It is an error if this version is missing. It is an error if the given version doesn't support the target framework (as a lower bound). It is acceptable to specify higher versions (even major versions), provided they exist on the machine. You can see this usage in the following example: + +``` console +dotnet publish -c release -o app --version=3.1.0 +``` + +Implementer notes: + +- Runtime selection is overridden by the specific version provided. +- It is an error if this version is unavailable. +- It is an error if this version doesn't support the given target framework (as a lower bound). + +## Determine latest Patch Versions + +You may want to learn the latest patch version for a given target framework that is available (independent of what is installed on the machine). This command will make a network call and simply print a version, must like `dotnet --version` does today. + +``` console +dotnet version --framework netcoreapp2.0 --latest +``` + +There are likely other changes that are coming for printing .NET Core versions. This command should align with these plans. The syntax above provides the general idea of the user experience. + +Forward-looking: It should be easy to write scripts that determine if the latest patch version is installed, then installs it at the command-line if it is not. + +## Open Issues + +These issues are related but will be covered in another design document. + +- Assembly loading +- Script loading, for example fsx and csx files. See [Runtime code generation using Roslyn compilations in .NET Core App](https://github.com/dotnet/roslyn/wiki/Runtime-code-generation-using-Roslyn-compilations-in-.NET-Core-App). + +## Technical Details + +This document takes some liberties, referring to `dotnet` as the version manager. From a user experience standpoint, this is true. From a technical standpoint, it is not. The version manager is implement in the following location, dependent on operating system: + +``` +~/dotnet/host/fxr/[version]/libhostfxr.dylib +``` diff --git a/docs/core/versions/index.md b/docs/core/versions/index.md index 72a6dbb6650fb..4021adcf326d3 100644 --- a/docs/core/versions/index.md +++ b/docs/core/versions/index.md @@ -27,6 +27,16 @@ With .NET Core 2.0, downloads show a single version number in their file name. T The use of a single version number makes it easier for users to know what version of the SDK to install on their dev machines, and what the corresponding version of the shared framework should be when time comes to provision a production environment. When downloading an SDK or runtime, the version number you see is going to be the same. +### Version binding + +.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are fully explored in the article on [binding](binding.md). + +One can think of these policies performing the following roles: + +* Provide an implicit "version manager" experience. +* Enable easy and efficient deployment of .NET Core, including security and reliability updates. +* Enable developers to use the latest tools and commands independent of target runtime. + ### Installers With .NET Core 2.0, downloads for the [daily builds](https://github.com/dotnet/core-setup#daily-builds) and [releases](https://www.microsoft.com/net/download/core) adhere to a new naming scheme that is easier to understand. diff --git a/docs/toc.md b/docs/toc.md index 6afcb5b925a38..e844ae6afdb90 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -120,6 +120,11 @@ ### [Unit Testing Published Output](core/testing/unit-testing-published-output.md) ### [Live unit testing .NET Core projects with Visual Studio](/visualstudio/test/live-unit-testing-start) ## [Versioning](core/versions/index.md) +<<<<<<< HEAD +======= +### [.NET Core Support](core/versions/lts-current.md) +### [.NET Core version binding](core/versions/binding.md) +>>>>>>> initial commit ## [Runtime IDentifier catalog](core/rid-catalog.md) ## [.NET Core SDK Overview](core/sdk.md) From e12edc89cf81bdb0249c34a4997b04c448f8d658 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 20 Jun 2018 16:15:32 -0400 Subject: [PATCH 02/13] first draft complete --- docs/core/versions/binding.md | 220 ++++++++++------------------------ 1 file changed, 66 insertions(+), 154 deletions(-) diff --git a/docs/core/versions/binding.md b/docs/core/versions/binding.md index 15ef25e058311..efcd112e269a5 100644 --- a/docs/core/versions/binding.md +++ b/docs/core/versions/binding.md @@ -1,40 +1,51 @@ -# .NET Core 2+ Version Binding +--- +title: .NET Core 2 and later version binding +description: Learn How the .NET runtime finds and chooses versions during build and run for your program +author: billwagner +ms.author: wiwagn +ms.date: 06/21/2018 +--- +# .NET Core 2 and later version binding -.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are defined in this document. +.NET Core provides a single entry-point for operating on projects and built applications with the `dotnet` command. You may have multiple runtime and SDK versions installed. The `dotnet` command must select a version in the following cases: -One can think of these policies performing the following roles: +- Select an SDK to use to run an SDK command (for example, with `dotnet new`). +- Select a runtime to target an application (for example, with `dotnet build`). +- Select a runtime to run an application (for example, with `dotnet run`). +- Select a runtime to publish an application (with `dotnet publish`). -- Providing an implicit "version manager" experience. -- Enabling easy and efficient deployment of .NET Core, including security and reliability updates. -- Enabling developers to use the latest tools and commands independent of target runtime. +The installation structure is machine global and in the path by default, enabling a developer to access all .NET Core versions from any command prompt. The structure enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. You may also use private .NET Core installations without use of the path. -## Experience +.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used. The different scenarios and policies are defined in this document. -.NET Core provides a single entry-point for operating on projects and built applications, specifically with the `dotnet` command. This experience relies on an installation structure that can include multiple runtime and SDK versions. This structure is machine global and in the path by default, enabling a developer to access all .NET Core versions from any command prompt. It also enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. This differs from other development platforms that require re-setting the path or setting an environmental value to use different platform versions. +These policies performing the following roles: -There is allowance for other scenarios, for example, for private .NET Core installations without use of the path. This document focusses more on the default behavior, but does call out opportunities to override this behavior. +- Provide an implicit "version manager" experience. +- Enable easy and efficient deployment of .NET Core, including security and reliability updates. +- Enable developers to use the latest tools and commands independent of target runtime. -The `dotnet` command must select a version in the following cases: +There are multiple points of version binding to consider: -- Select an SDK to use to run an SDK command (for example, with `dotnet new`). -- Select a runtime to target an application (for example, with `dotnet build`). -- Select a runtime to run an application (for example, with `dotnet run`). -- Select a runtime to publish an application (with `dotnet publish`). +- Select an [SDK](#select-an-sdk-version). +- Select a [target framework](#select-a-target-framework) for the application. +- Select a [minimum runtime version](#minimum-required-runtime-version) +- Selecting a runtime to run on -## Selecting an SDK -The first developer experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must select a version of the SDK to use to satisfy these commands. .NET Core has a "use the latest SDK" policy. This means that you will use the .NET Core 99.9 SDK if you install it on a machine, even if you are using the SDK command to do .NET Core 2.0 development. +## Select an SDK version -The advantage of this policy is that you can take advantage of the latest SDK features and improvements while continuing to target earlier .NET Core versions. This is logically similar to using C# 7 with .NET Framework 4.5 (which also works). It is quite likely many developers will target multiple versions of .NET Core across a set of projects. It's nice that you can use the same tools for all of them. +Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK. You will use the .NET Core 99.9 SDK when it's installed, even if you're using the SDK command for .NET Core 2.0 development. -You can configure `dotnet` to use a different version of the SDK by specifying that version in a [global.json file](https://docs.microsoft.com/dotnet/articles/core/tools/global-json). As a consequence of the "use latest" policy, you would only ever use `global.json` to specify a .NET Core version that is earlier than the latest installed version. +You take advantage of the latest SDK features and improvements while targeting earlier .NET Core versions. You may target multiple versions of .NET Core on multiple projects. You can use the same tools for all projects. -You can use `global.json` at a variety of scopes: +When needed, you configure `dotnet` to use a different 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. + +`global.json`can be used at different scopes: - Per project, placed beside the project file. - For a set of projects, placed at a common [grand-]parent for all of the projects. This location can be as high in the directory structure as the root of a drive. -You can see the `global.json` syntax in the following example: +The following example shows the `global.json` syntax: ``` json { @@ -44,33 +55,23 @@ You can see the `global.json` syntax in the following example: } ``` -The `global.json` file is an existing format and associated concept that is part of the .NET Core 1.0 tools. It is not new with .NET Core 2.0. The file fulfills a critical role, to enable developers to lock a specific app or set of apps to an earlier SDK than the latest on the machine. The need for this capability is most obvious for developers that need to continue using the preview2 sdk to use project.json-based applications. We will revisit the design of this file in a later release. We will also want to understand how often it is even used to better understand how important the scenario is. The less it is used, the more likely the file will stay as-is. +You only use `global.json` to specify a version when you must lock a specific app or set of apps to an earlier SDK than the latest on the machine. -Implementer notes: +The process for selecting an SDK version is: - `dotnet` binds to latest SDK by default. -- This behavior can be overridden by global.json. -- The first global.json file found is selected, iteratively reverse-navigating the path from the current working directory. - -## Building an application - -You can build an application from source with `dotnet build` or `dotnet run` (the latter does more than is covered in this section). - -There are multiple points of version binding to consider: - -- Selecting an SDK. -- Defining the target framework for the application. -- Defining a minimum runtime version. +- You can override the latest version using global.json. +- `dotnet` uses the first global.json file found, iteratively reverse-navigating the path upward from the current working directory. -The process of selecting an SDK is described earlier in the document. +## Select a target SDK -The target framework is defined in the project file by setting a property in the following form: +You specify the target framework in the project file. Set the `TargetFramework` as shown in the following example: ``` xml netcoreapp2.0 ``` -Multiple target frameworks can also be set if you need to build different code for different targets. This scenario is more common for libraries, but can be done with applications as well. You can do this by using a `TargetFrameworks` property (plural of TargetFramework). The target frameworks will be semicolon-delimited as you can see the following example: +You can set multiple target frameworks if you need to build different code for different targets. 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 will be semicolon-delimited as shown in the following example: ``` xml netcoreapp2.0;net47 @@ -94,171 +95,82 @@ You can override the minimum runtime patch version (to higher or lower versions) 2.0.4 ``` -In the case that you target multiple target frameworks, you need to condition the minimum runtime patch version to the specific .NET Core target framework, as you can see in the following example: +When you target multiple target frameworks, you must specify the minimum runtime patch version to the specific .NET Core target framework, as shown in the following example: ``` xml netcoreapp2.0;net47 -2.0.4 +2.0.4 ``` -Implementer notes: +A given SDK supports a fixed set of target frameworks. Typically, the target frameworks are the SDK framework version and a set of earlier versions. -- A given SDK supports a fixed set of target frameworks. -- It is an error to target a framework outside that set. -- The SDK defines the minimum runtime patch version (set at the .0 patch) for a given target framework. -- This version can be overridden in a project file. +## Minimum required runtime version -## Run from Source with dotnet run +You run an application from source with `dotnet run`. `dotnet run` both builds and runs an application. -You can run an application from source with `dotnet run`. `dotnet run` both builds and runs an application. +The built application runs on machines that satisfy the minimum required runtime patch version, stored in the `*.runtimeconfig.json` file. The highest patch version is selected. For example, the `2.0.4` runtime is selected in the case that the minimum runtime version is `2.0.0` while `2.0.0`, `2.0.1` and `2.0.4` are all installed on the machine. Higher minor or major versions (for example, `2.1.1` or `3.0.1`) won't be considered. Lower versions also won't be considered. -There are multiple points of version binding to consider: - -- Selecting an SDK -- Defining a target framework for the appliction -- Defining a minimum runtime patch version -- Selecting a runtime to run on - -The process of selecting an SDK and building an application is described earlier in the document. - -The built application will be run on machines that satisfy the minimum required runtime patch version, stored in the `*.runtimeconfig.json` file. The highest patch version will be selected. For example, the `2.0.4` runtime will be selected in the case that the minimum runtime version is `2.0.0` while `2.0.0`, `2.0.1` and `2.0.4` are all resident on the machine. Higher minor or major versions (for example, `2.1.1` or `3.0.1`) will not be considered. Lower versions will also not be considered. - -Implementer notes: - -- It is an error if the minimum version specified for an application is not satisfied. -- `dotnet` binds to latest runtime patch version (within a given major.minor version family). - -## Run from bin directory with dotnet myapp.dll +It is an error if the minimum version specified for an application is not satisfied. However, you may run an application on a machine that is missing the runtime required by the application. If a higher minor version is installed, the minor version is used instead of failing. Higher major versions will not be used to load applications. This behavior is referred to as "minor version roll-forward." -You can build and then run an application, essentially performing `dotnet run` as two separate steps, as seen in the following example: - -``` console -dotnet build -dotnet bin\Debug\netcorapp2.0\myapp.dll -``` - -This scenario is an equivalence class for `dotnet run`. - -## Run a published application with dotnet myapp.dll - -You can publish an application to prepare it for distribution to other runtime environments, as seen in the following example: - -``` console -dotnet publish -c release -o app -dotnet .\app\app.dll -``` - -This scenario is an equivalence class for `dotnet run`. - -## Run a published application with the required runtime missing - -You may run an application on a machine that is missing the runtime required by the application. If the required runtime is missing and a higher minor version is installed, the minor version should be used instead of failing to load the application. Higher major versions will not be used to load applications. This behavior shall be called "minor version roll-forward." - -To illustrate this behavior, for an application requiring 2.0.4, `dotnet` would search and bind to a runtime in this order (picking the first it finds or showing error): +Consider an application requiring 2.0.4, `dotnet` would search and bind to a runtime in this order: - 2.0.* (highest patch version; ensure that it satisfies 2.0.4 as a lower bound) - 2.* (highest minor version) -- A helpful error message appears (see the message that follows) + +If neither is found, you see an error message similar to the following: > This application requires .NET Core 2.0.4. Please install .NET Core 2.0.4 or a higher compatible version. > Please see https://aka.ms/install-dotnet-core to learn about .NET Core installation and runtime versioning. -A few usage examples may help to demonstrate the desired behavior: +A few usage examples demonstrate the desired behavior: - 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. -- 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error with a helpful error message is printed. +- 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is printed. - 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. -- 2.0.4 is required. No 2.x versions are installed. 3.0.0 is installed. An error with a helpful error message is printed. - -There is a trade-off for this behavior between compatibility and convenience. .NET Core minor versions are intended to be very compatible. It is therefore reasonable to choose the convenience experience without significant concern for compatibility breaks. +- 2.0.4 is required. No 2.x versions are installed. 3.0.0 is installed. An error message is printed. -The following example is a somewhat unfortunate side-effect behavior of the algorithm that is important to realize: +Minor version roll-forward has one side-effect that may affect end users. Consider the following scenario: - 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is installed. It is used. - 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. - It is possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. -The treatment of NuGet dependencies needs to be understood as well. A given application might be built for .NET Core 2.0 but run on .NET Core 2.1 due to this algorithm. There may be later versions of an application's NuGet dependencies that target .NET Core 2.1. These later versions will not be considered or consulted. All NuGet dependencies should be already resolved as part of the published application layout, residing as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. +You also need to understand how NuGet dependencies are treated. An application might be built for .NET Core 2.0 but run on .NET Core 2.1 due to this algorithm. There may be later versions of an application's NuGet dependencies that target .NET Core 2.1. These later versions are not considered or installed. All NuGet dependencies are resolved as part of the publish operation and reside as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. -There are some scenarios where ASP.NET packages will be deployed via a web host rather than with a published application. In those cases, it is recommended that web hosters correctly configure their environments based on published guidance such that all supported ASP.NET applications run correctly. +Occasionally, ASP.NET packages are deployed via a web host rather than with a published application. In those cases, the web host should correctly configure their environments based on published guidance such that all supported ASP.NET applications run correctly. -Implementer notes: +Developers should remember the following rules: - Runtimes are searched for in the following order (the first found is loaded): - - Highest patch version (check that the minimum runtime path version is satisfied, otherwise error) - - Highest minor version -- If an acceptable runtime is not found, then error. + - Highest patch version (check that the minimum runtime path version is satisfied, otherwise error) + - Highest minor version +- If an acceptable runtime is not found, the application does not run and an error message explains why. ## Publish a self-contained application -You can publish an application as a self-contained distribution. The advantage of this approach is that it includes .NET Core so does not require it is a dependency in runtime environments. As a result, runtime binding occurs at publishing time not run-time. - -There are multiple points of version binding to consider: - -- Selecting an SDK -- Defining a target framework for the application -- Selecting a runtime to publish - -The process of selecting an SDK and building an application is described earlier in the document. +You can publish an application as a **self-contained distribution**. This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. The publishing process will select 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, independent of the existence of earlier patch versions or minimum runtime patch version values. This differs from `dotnet build` runtime selection for two reasons: -- The application doesn't need to align with a hosting environment. -- The developer is generating a final configuration for the application (that cannot be practically modified). The best runtime choice is the latest installed runtime patch version, both because that is the same version as was used for development and because it will have the latest (per the machine) security and reliability fixes. +- The application doesn't specify a hosting environment. +- The developer generates a final configuration for the application (that can't be practically modified). The best runtime choice is the latest installed runtime patch version. It's the same version used for development and it has the latest (per the machine) security and reliability fixes. -Note that the runtimeframeworkversion element will override the default version policy if that element is present in the project file. +Note that the `runtimeframeworkversion` element will override the default version policy if that element is present in the project file. -Implementer Notes: - -- It is an error if the minimum version specified for an application is not satisfied. -- `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). -- `dotnet publish` does not support the roll-forward semantics of `dotnet run` +It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. ## Publish an application with a specific .NET Core version -Developers can specify a .NET Core runtime version within a project file. That's convenient for developers because they typically work on one project at a time and typically edit project files, but not for CI/CD flows or human software deployers who manage many projects and who do not typically edit project files. Instead `dotnet publish` accepts a version to use for publishing for both self-contained and framework-dependent apps. One can imagine Visual Studio Team Systems offering a setting to specify a runtime version within a build configuration UI that affects publish without needing to update source code. +`dotnet publish` accepts a version to use for publishing for both self-contained and framework-dependent apps. This is primarily for CI/CD scenarios or other times when you must publish an application, but can't update source code. -You can publish with the latest runtime patch version for the given target framework, by specifying `--latest`. This argument has the same default runtime binding behavior for publishing self-contained applications. You can see this usage in the following example: +You publish with the latest runtime patch version for the given target framework specifying `--latest`. This argument has the same default runtime binding behavior for publishing self-contained applications. You can see this in the following example: ``` console dotnet publish -c release -o app --latest ``` -You can publish with a specific runtime patch version for the given target framework, by specifying `--version=[version]`. It is an error if this version is missing. It is an error if the given version doesn't support the target framework (as a lower bound). It is acceptable to specify higher versions (even major versions), provided they exist on the machine. You can see this usage in the following example: +You publish with a specific runtime patch version for the given target framework specifying `--version=[version]`. It is an error if this version is missing. It's an error if the given version doesn't support the target framework (as a lower bound). You may specify higher versions (even major versions), provided they exist on the machine. You can see this usage in the following example: ``` console dotnet publish -c release -o app --version=3.1.0 ``` - -Implementer notes: - -- Runtime selection is overridden by the specific version provided. -- It is an error if this version is unavailable. -- It is an error if this version doesn't support the given target framework (as a lower bound). - -## Determine latest Patch Versions - -You may want to learn the latest patch version for a given target framework that is available (independent of what is installed on the machine). This command will make a network call and simply print a version, must like `dotnet --version` does today. - -``` console -dotnet version --framework netcoreapp2.0 --latest -``` - -There are likely other changes that are coming for printing .NET Core versions. This command should align with these plans. The syntax above provides the general idea of the user experience. - -Forward-looking: It should be easy to write scripts that determine if the latest patch version is installed, then installs it at the command-line if it is not. - -## Open Issues - -These issues are related but will be covered in another design document. - -- Assembly loading -- Script loading, for example fsx and csx files. See [Runtime code generation using Roslyn compilations in .NET Core App](https://github.com/dotnet/roslyn/wiki/Runtime-code-generation-using-Roslyn-compilations-in-.NET-Core-App). - -## Technical Details - -This document takes some liberties, referring to `dotnet` as the version manager. From a user experience standpoint, this is true. From a technical standpoint, it is not. The version manager is implement in the following location, dependent on operating system: - -``` -~/dotnet/host/fxr/[version]/libhostfxr.dylib -``` From 63365169484a26785745cec76402ef95697a150c Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 20 Jun 2018 16:39:33 -0400 Subject: [PATCH 03/13] proofread and grammar check --- docs/core/versions/binding.md | 46 +++++++++++++++-------------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/docs/core/versions/binding.md b/docs/core/versions/binding.md index efcd112e269a5..59e050588d746 100644 --- a/docs/core/versions/binding.md +++ b/docs/core/versions/binding.md @@ -7,24 +7,24 @@ ms.date: 06/21/2018 --- # .NET Core 2 and later version binding -.NET Core provides a single entry-point for operating on projects and built applications with the `dotnet` command. You may have multiple runtime and SDK versions installed. The `dotnet` command must select a version in the following cases: +.NET Core provides a single entry-point for operating on projects and built applications with the `dotnet` command. You may have multiple runtime and SDK versions installed. The `dotnet` command must: - Select an SDK to use to run an SDK command (for example, with `dotnet new`). - Select a runtime to target an application (for example, with `dotnet build`). - Select a runtime to run an application (for example, with `dotnet run`). - Select a runtime to publish an application (with `dotnet publish`). -The installation structure is machine global and in the path by default, enabling a developer to access all .NET Core versions from any command prompt. The structure enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. You may also use private .NET Core installations without use of the path. +The installation structure is machine global and in the path by default. This rule enables a developer to access all .NET Core versions from any command prompt. The structure enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. You may also use private .NET Core installations without use of the path. -.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used. The different scenarios and policies are defined in this document. +.NET Core applies a set of policies that determines which versions of the .NET Core runtime and SDK are used. The different scenarios and policies are defined in this document. -These policies performing the following roles: +These policies perform the following roles: - Provide an implicit "version manager" experience. - Enable easy and efficient deployment of .NET Core, including security and reliability updates. - Enable developers to use the latest tools and commands independent of target runtime. -There are multiple points of version binding to consider: +There are multiple actions where version binding takes place: - Select an [SDK](#select-an-sdk-version). - Select a [target framework](#select-a-target-framework) for the application. @@ -34,9 +34,9 @@ There are multiple points of version binding to consider: ## Select an SDK version -Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK. You will use the .NET Core 99.9 SDK when it's installed, even if you're using the SDK command for .NET Core 2.0 development. +Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK. You'll use the .NET Core 99.9 SDK when it's installed, even if you're using the SDK command for .NET Core 2.0 development. -You take advantage of the latest SDK features and improvements while targeting earlier .NET Core versions. You may target multiple versions of .NET Core on multiple projects. You can use the same tools for all projects. +You take advantage of the latest SDK features and improvements while targeting earlier .NET Core versions. You can target multiple versions of .NET Core on different projects, using the same SDK tools for all projects. When needed, you configure `dotnet` to use a different 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. @@ -71,25 +71,19 @@ You specify the target framework in the project file. Set the `TargetFramework` netcoreapp2.0 ``` -You can set multiple target frameworks if you need to build different code for different targets. 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 will be semicolon-delimited as shown in the following example: +You set multiple target frameworks if you need to build different code for different environments. 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 will be semicolon-delimited as shown in the following example: ``` xml netcoreapp2.0;net47 ``` -A given SDK will support a fixed set of frameworks, typically capped to the target framework of the runtime(s) it includes. 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 will support `netcoreapp1.0`, `netcoreapp1.1` and `netcoreapp2.0` but not `netcoreapp2.1` (or higher). You will need to install the .NET Core 2.1 SDK in order to build for `netcoreapp2.1`. +A given SDK will support a fixed set of frameworks, typically capped to the target framework of the runtime(s) it includes. 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 will support `netcoreapp1.0`, `netcoreapp1.1`, and `netcoreapp2.0` but not `netcoreapp2.1` (or higher). You'll need to install the .NET Core 2.1 SDK in order to build for `netcoreapp2.1`. .NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK will be capped to `netstandard2.0`. -A given SDK will define a fixed minimum runtime patch version for each target framework that it supports. The minimum runtime patch version will be maintained at the `.0` version (for example, `2.0.0`) for the lifetime of a major/minor runtime version family. This policy makes deploying patches a web hoster concern and not a developer concern. +A given SDK defines a fixed minimum runtime patch version for each target framework that it supports. The minimum runtime patch version is maintained at the `.0` version (for example, `2.0.0`) for the lifetime of a major/minor runtime version family. -Hosters and other users have reported challenges with the .NET Core 1.x behavior, where the minimum patch version increases with each .NET Core SDK release. See: [Reconsider implicitly using the latest patch version of the targeted version of .NET Core in the SDK](https://github.com/dotnet/sdk/issues/983). This proposal is intended to resolve their feedback. - -The SDK stores the minimum patch version for each supported target framework in the `~\dotnet\sdk\1.0.0\Sdks\Microsoft.NET.Sdk\build\Microsoft.NET.Sdk.DefaultItems.targets` file. - -The minimum runtime patch version is stored in the application directory in the `*.runtimeconfig.json` file. This value is used as part of runtime selection. You are not intended to edit this file. - -You can override the minimum runtime patch version (to higher or lower versions) in the project file, as you can see in the following example: +You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example: ``` xml 2.0.4 @@ -110,19 +104,19 @@ You run an application from source with `dotnet run`. `dotnet run` both builds a The built application runs on machines that satisfy the minimum required runtime patch version, stored in the `*.runtimeconfig.json` file. The highest patch version is selected. For example, the `2.0.4` runtime is selected in the case that the minimum runtime version is `2.0.0` while `2.0.0`, `2.0.1` and `2.0.4` are all installed on the machine. Higher minor or major versions (for example, `2.1.1` or `3.0.1`) won't be considered. Lower versions also won't be considered. -It is an error if the minimum version specified for an application is not satisfied. However, you may run an application on a machine that is missing the runtime required by the application. If a higher minor version is installed, the minor version is used instead of failing. Higher major versions will not be used to load applications. This behavior is referred to as "minor version roll-forward." +It's an error if the minimum version specified for an application is not satisfied. However, you may run an application on a machine that is missing the runtime required by the application. If a higher minor version is installed, the minor version is used instead of failing. Higher major versions will not be used to load applications. This behavior is referred to as "minor version roll-forward." Consider an application requiring 2.0.4, `dotnet` would search and bind to a runtime in this order: - 2.0.* (highest patch version; ensure that it satisfies 2.0.4 as a lower bound) - 2.* (highest minor version) -If neither is found, you see an error message similar to the following: +If neither is found, you see an error message similar to the following example: > This application requires .NET Core 2.0.4. Please install .NET Core 2.0.4 or a higher compatible version. > Please see https://aka.ms/install-dotnet-core to learn about .NET Core installation and runtime versioning. -A few usage examples demonstrate the desired behavior: +A few usage examples demonstrate the behavior: - 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. - 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is printed. @@ -131,11 +125,11 @@ A few usage examples demonstrate the desired behavior: Minor version roll-forward has one side-effect that may affect end users. Consider the following scenario: -- 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is installed. It is used. +- 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is installed. 2.2.2 is used. - 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. -- It is possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. +- It's possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. -You also need to understand how NuGet dependencies are treated. An application might be built for .NET Core 2.0 but run on .NET Core 2.1 due to this algorithm. There may be later versions of an application's NuGet dependencies that target .NET Core 2.1. These later versions are not considered or installed. All NuGet dependencies are resolved as part of the publish operation and reside as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. +NuGet dependencies are treated differently. An application might be built for .NET Core 2.0 but run on .NET Core 2.1 due to this algorithm. There may be later versions of an application's NuGet dependencies that target .NET Core 2.1. These later versions aren't considered or installed. All NuGet dependencies are resolved as part of the publish operation and reside as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. Occasionally, ASP.NET packages are deployed via a web host rather than with a published application. In those cases, the web host should correctly configure their environments based on published guidance such that all supported ASP.NET applications run correctly. @@ -150,12 +144,12 @@ Developers should remember the following rules: You can publish an application as a **self-contained distribution**. This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. -The publishing process will select 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, independent of the existence of earlier patch versions or minimum runtime patch version values. This differs from `dotnet build` runtime selection for two reasons: +The publishing process will select 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, independent of the existence of earlier patch versions or minimum runtime patch version values. The publishing process differs from `dotnet build` runtime selection for two reasons: - The application doesn't specify a hosting environment. - The developer generates a final configuration for the application (that can't be practically modified). The best runtime choice is the latest installed runtime patch version. It's the same version used for development and it has the latest (per the machine) security and reliability fixes. -Note that the `runtimeframeworkversion` element will override the default version policy if that element is present in the project file. +The `runtimeframeworkversion` element will override the default version policy if that element is present in the project file. It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. @@ -163,7 +157,7 @@ It is an error if the minimum version specified for an application is not satisf `dotnet publish` accepts a version to use for publishing for both self-contained and framework-dependent apps. This is primarily for CI/CD scenarios or other times when you must publish an application, but can't update source code. -You publish with the latest runtime patch version for the given target framework specifying `--latest`. This argument has the same default runtime binding behavior for publishing self-contained applications. You can see this in the following example: +You publish with the latest runtime patch version for the given target framework specifying `--latest`. This argument has the same default runtime binding behavior for publishing self-contained applications. See the following example: ``` console dotnet publish -c release -o app --latest From e3f3762f1318b7514d6ef8f27b5725687e08fe92 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 21 Jun 2018 10:35:34 -0400 Subject: [PATCH 04/13] respond to feedback --- docs/core/deploying/index.md | 2 +- docs/core/versions/binding.md | 51 +++++++++++++++++------------------ 2 files changed, 25 insertions(+), 28 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 8e56a40f0bcc7..bad579a37469b 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -36,7 +36,7 @@ There are also a few disadvantages: ## Self-contained deployments (SCD) -For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. +For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. For more information on version binding at runtime see the topic on [version binding in .NET Core](../versions/binding.md) FDD and SCD deployments use separate host executables, so you can sign a host executable for an SCD with your publisher signature. diff --git a/docs/core/versions/binding.md b/docs/core/versions/binding.md index 59e050588d746..e9d85581700ee 100644 --- a/docs/core/versions/binding.md +++ b/docs/core/versions/binding.md @@ -1,11 +1,13 @@ --- title: .NET Core 2 and later version binding -description: Learn How the .NET runtime finds and chooses versions during build and run for your program +description: Learn How the .NET runtime finds and chooses versions during build and run for your program. author: billwagner ms.author: wiwagn ms.date: 06/21/2018 --- -# .NET Core 2 and later version binding +# .NET Core version binding + +[!INCLUDE [topic-appliesto-net-core-2plus](../../../includes/topic-appliesto-net-core-2plus.md)] .NET Core provides a single entry-point for operating on projects and built applications with the `dotnet` command. You may have multiple runtime and SDK versions installed. The `dotnet` command must: @@ -27,20 +29,19 @@ These policies perform the following roles: There are multiple actions where version binding takes place: - Select an [SDK](#select-an-sdk-version). -- Select a [target framework](#select-a-target-framework) for the application. -- Select a [minimum runtime version](#minimum-required-runtime-version) -- Selecting a runtime to run on - +- Select a [target framework](#build-time-version-binding) for the application. +- Select a [minimum runtime version](#runtime-version-binding). +- Selecting a runtime to run on. ## Select an SDK version -Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK. You'll use the .NET Core 99.9 SDK when it's installed, even if you're using the SDK command for .NET Core 2.0 development. +Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK by default. If you've installed the .NET Core 99.9 SDK, the `dotnet` command uses .NET Core SDK 99.9 even when you're targeting .NET Core 2.0 development. Note that this is true for preview versions as well as released versions. -You take advantage of the latest SDK features and improvements while targeting earlier .NET Core versions. You can target multiple versions of .NET Core on different projects, using the same SDK tools for all projects. +You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core versions. You can target multiple versions of .NET Core on different projects, using the same SDK tools for all projects. When needed, you configure `dotnet` to use a different 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. -`global.json`can be used at different scopes: +`global.json` can be used at different scopes: - Per project, placed beside the project file. - For a set of projects, placed at a common [grand-]parent for all of the projects. This location can be as high in the directory structure as the root of a drive. @@ -55,31 +56,29 @@ The following example shows the `global.json` syntax: } ``` -You only use `global.json` to specify a version when you must lock a specific app or set of apps to an earlier SDK than the latest on the machine. - The process for selecting an SDK version is: -- `dotnet` binds to latest SDK by default. -- You can override the latest version using global.json. -- `dotnet` uses the first global.json file found, iteratively reverse-navigating the path upward from the current working directory. +- `dotnet` searches for a `global.json` file iteratively reverse-navigating the path upward from the current working directory. +- `dotnet` uses the SDK specified in the first `global.json` found. +- `dotnet` binds to the latest installed SDK if no `global.json` is found. -## Select a target SDK +## Build time version binding -You specify the target framework in the project file. Set the `TargetFramework` as shown in the following example: +You build your project against APIs defined in a **Target Framework Moniker** (TFM). You specify the target framework in the project file. Set the `TargetFramework` element in your project file as shown in the following example: ``` xml netcoreapp2.0 ``` -You set multiple target frameworks if you need to build different code for different environments. 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 will be semicolon-delimited as shown in the following example: +You may build your project against multiple frameworks. 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 will be semicolon-delimited as shown in the following example: ``` xml netcoreapp2.0;net47 ``` -A given SDK will support a fixed set of frameworks, typically capped to the target framework of the runtime(s) it includes. 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 will support `netcoreapp1.0`, `netcoreapp1.1`, and `netcoreapp2.0` but not `netcoreapp2.1` (or higher). You'll need to install the .NET Core 2.1 SDK in order to build for `netcoreapp2.1`. +A given SDK supports a fixed set of frameworks, typically capped to the target framework of the runtimes it includes. 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 will support `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`. -.NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK will be capped to `netstandard2.0`. +.NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK is capped to `netstandard2.0`. A given SDK defines a fixed minimum runtime patch version for each target framework that it supports. The minimum runtime patch version is maintained at the `.0` version (for example, `2.0.0`) for the lifetime of a major/minor runtime version family. @@ -89,7 +88,7 @@ You can override the minimum runtime patch version (to higher or lower versions) 2.0.4 ``` -When you target multiple target frameworks, you must specify the minimum runtime patch version to the specific .NET Core target framework, as shown in the following example: +When you target multiple frameworks, you must specify the minimum runtime patch version to the specific .NET Core target framework, as shown in the following example: ``` xml netcoreapp2.0;net47 @@ -98,13 +97,11 @@ When you target multiple target frameworks, you must specify the minimum runtime A given SDK supports a fixed set of target frameworks. Typically, the target frameworks are the SDK framework version and a set of earlier versions. -## Minimum required runtime version - -You run an application from source with `dotnet run`. `dotnet run` both builds and runs an application. +## Runtime version binding -The built application runs on machines that satisfy the minimum required runtime patch version, stored in the `*.runtimeconfig.json` file. The highest patch version is selected. For example, the `2.0.4` runtime is selected in the case that the minimum runtime version is `2.0.0` while `2.0.0`, `2.0.1` and `2.0.4` are all installed on the machine. Higher minor or major versions (for example, `2.1.1` or `3.0.1`) won't be considered. Lower versions also won't be considered. +You run an application from source with [`dotnet run`](../tools/dotnet-run.md). `dotnet run` both builds and runs an application. -It's an error if the minimum version specified for an application is not satisfied. However, you may run an application on a machine that is missing the runtime required by the application. If a higher minor version is installed, the minor version is used instead of failing. Higher major versions will not be used to load applications. This behavior is referred to as "minor version roll-forward." +The built application runs on machines that satisfy the minimum required runtime patch version, stored in the `*.runtimeconfig.json` file. The highest patch version is selected. For example, the `2.0.4` runtime is selected in the case that the minimum runtime version is `2.0.0` while `2.0.0`, `2.0.1` and `2.0.4` are all installed on the machine. This behavior is referred to as "minor version roll-forward." Higher minor or major versions (for example, `2.1.1` or `3.0.1`) won't be considered. Lower versions also won't be considered. When no acceptable runtime is installed, the application will not run. Consider an application requiring 2.0.4, `dotnet` would search and bind to a runtime in this order: @@ -114,7 +111,7 @@ Consider an application requiring 2.0.4, `dotnet` would search and bind to a run If neither is found, you see an error message similar to the following example: > This application requires .NET Core 2.0.4. Please install .NET Core 2.0.4 or a higher compatible version. -> Please see https://aka.ms/install-dotnet-core to learn about .NET Core installation and runtime versioning. +> Please see https://www.microsoft.com/net/download to learn about .NET Core installation and runtime versioning. A few usage examples demonstrate the behavior: @@ -142,7 +139,7 @@ Developers should remember the following rules: ## Publish a self-contained application -You can publish an application as a **self-contained distribution**. This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. +You can publish an application as a [**self-contained distribution**](../deploying/#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. The publishing process will select 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, independent of the existence of earlier patch versions or minimum runtime patch version values. The publishing process differs from `dotnet build` runtime selection for two reasons: From 14b2a636a030d5795dd959451478b1cc75e5413d Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 26 Jun 2018 15:11:36 -0400 Subject: [PATCH 05/13] fix merge --- docs/toc.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/toc.md b/docs/toc.md index e844ae6afdb90..90934c56eb97d 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -120,11 +120,8 @@ ### [Unit Testing Published Output](core/testing/unit-testing-published-output.md) ### [Live unit testing .NET Core projects with Visual Studio](/visualstudio/test/live-unit-testing-start) ## [Versioning](core/versions/index.md) -<<<<<<< HEAD -======= ### [.NET Core Support](core/versions/lts-current.md) ### [.NET Core version binding](core/versions/binding.md) ->>>>>>> initial commit ## [Runtime IDentifier catalog](core/rid-catalog.md) ## [.NET Core SDK Overview](core/sdk.md) From 6b4079176beb7e11b293f5f094936bb8c9418f77 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 26 Jun 2018 15:15:26 -0400 Subject: [PATCH 06/13] fix a bad merge --- docs/toc.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/toc.md b/docs/toc.md index 90934c56eb97d..3bd43b4065186 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -120,9 +120,7 @@ ### [Unit Testing Published Output](core/testing/unit-testing-published-output.md) ### [Live unit testing .NET Core projects with Visual Studio](/visualstudio/test/live-unit-testing-start) ## [Versioning](core/versions/index.md) -### [.NET Core Support](core/versions/lts-current.md) ### [.NET Core version binding](core/versions/binding.md) - ## [Runtime IDentifier catalog](core/rid-catalog.md) ## [.NET Core SDK Overview](core/sdk.md) ## [.NET Core CLI Tools](core/tools/index.md) From 4e1a906b94102c8e682d646f15a5ed6baa98d7d2 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 26 Jun 2018 15:58:10 -0400 Subject: [PATCH 07/13] address detailed comments. --- docs/core/versions/binding.md | 21 +++++++++------------ docs/core/versions/index.md | 1 - 2 files changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/core/versions/binding.md b/docs/core/versions/binding.md index e9d85581700ee..ea2e08dd60c3e 100644 --- a/docs/core/versions/binding.md +++ b/docs/core/versions/binding.md @@ -1,6 +1,6 @@ --- -title: .NET Core 2 and later version binding -description: Learn How the .NET runtime finds and chooses versions during build and run for your program. +title: .NET Core version binding +description: Learn How the .NET core runtime finds and chooses versions during build and run for your program. author: billwagner ms.author: wiwagn ms.date: 06/21/2018 @@ -16,13 +16,12 @@ ms.date: 06/21/2018 - Select a runtime to run an application (for example, with `dotnet run`). - Select a runtime to publish an application (with `dotnet publish`). -The installation structure is machine global and in the path by default. This rule enables a developer to access all .NET Core versions from any command prompt. The structure enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. You may also use private .NET Core installations without use of the path. +The installation structure is machine global and in the path by default. The structure enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. You may also use private .NET Core installations without use of the path. .NET Core applies a set of policies that determines which versions of the .NET Core runtime and SDK are used. The different scenarios and policies are defined in this document. These policies perform the following roles: -- Provide an implicit "version manager" experience. - Enable easy and efficient deployment of .NET Core, including security and reliability updates. - Enable developers to use the latest tools and commands independent of target runtime. @@ -88,14 +87,14 @@ You can override the minimum runtime patch version (to higher or lower versions) 2.0.4 ``` -When you target multiple frameworks, you must specify the minimum runtime patch version to the specific .NET Core target framework, as shown in the following example: + The `RuntimeFrameworkVersion` element will override the default version policy if that element is present in the project file. When you target multiple frameworks, you must specify the minimum runtime patch version to the specific target framework, as shown in the following example for .NET Core: ``` xml netcoreapp2.0;net47 2.0.4 ``` -A given SDK supports a fixed set of target frameworks. Typically, the target frameworks are the SDK framework version and a set of earlier versions. +A given SDK supports a fixed set of target frameworks. Typically, the target frameworks are the SDK framework version and all earlier versions. ## Runtime version binding @@ -126,9 +125,7 @@ Minor version roll-forward has one side-effect that may affect end users. Consid - 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. - It's possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. -NuGet dependencies are treated differently. An application might be built for .NET Core 2.0 but run on .NET Core 2.1 due to this algorithm. There may be later versions of an application's NuGet dependencies that target .NET Core 2.1. These later versions aren't considered or installed. All NuGet dependencies are resolved as part of the publish operation and reside as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. - -Occasionally, ASP.NET packages are deployed via a web host rather than with a published application. In those cases, the web host should correctly configure their environments based on published guidance such that all supported ASP.NET applications run correctly. +All NuGet dependencies are resolved as part of the publish operation and reside as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. Developers should remember the following rules: @@ -139,14 +136,14 @@ Developers should remember the following rules: ## Publish a self-contained application -You can publish an application as a [**self-contained distribution**](../deploying/#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. +You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. The publishing process will select 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, independent of the existence of earlier patch versions or minimum runtime patch version values. The publishing process differs from `dotnet build` runtime selection for two reasons: - The application doesn't specify a hosting environment. -- The developer generates a final configuration for the application (that can't be practically modified). The best runtime choice is the latest installed runtime patch version. It's the same version used for development and it has the latest (per the machine) security and reliability fixes. +- The developer generates a target framework for the application. -The `runtimeframeworkversion` element will override the default version policy if that element is present in the project file. +The target framework (including the latest instealled security patches) are packaged with the application. It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. diff --git a/docs/core/versions/index.md b/docs/core/versions/index.md index 4021adcf326d3..3bbc830f7aab0 100644 --- a/docs/core/versions/index.md +++ b/docs/core/versions/index.md @@ -33,7 +33,6 @@ The use of a single version number makes it easier for users to know what versio One can think of these policies performing the following roles: -* Provide an implicit "version manager" experience. * Enable easy and efficient deployment of .NET Core, including security and reliability updates. * Enable developers to use the latest tools and commands independent of target runtime. From dbc2bddec4358c4bf6bd153d9324746b5a7ec45d Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 26 Jun 2018 16:54:10 -0400 Subject: [PATCH 08/13] one more round of detailed changes. --- docs/core/versions/binding.md | 43 ++++++++++++++--------------------- 1 file changed, 17 insertions(+), 26 deletions(-) diff --git a/docs/core/versions/binding.md b/docs/core/versions/binding.md index ea2e08dd60c3e..c639dde3f30c5 100644 --- a/docs/core/versions/binding.md +++ b/docs/core/versions/binding.md @@ -1,12 +1,15 @@ --- title: .NET Core version binding -description: Learn How the .NET core runtime finds and chooses versions during build and run for your program. +description: Learn How .NET Core finds and chooses runtime versions for your program. author: billwagner ms.author: wiwagn ms.date: 06/21/2018 --- # .NET Core version binding +Rework notes: Keep clear separation between SDK & runtime selection. + + [!INCLUDE [topic-appliesto-net-core-2plus](../../../includes/topic-appliesto-net-core-2plus.md)] .NET Core provides a single entry-point for operating on projects and built applications with the `dotnet` command. You may have multiple runtime and SDK versions installed. The `dotnet` command must: @@ -30,27 +33,29 @@ There are multiple actions where version binding takes place: - Select an [SDK](#select-an-sdk-version). - Select a [target framework](#build-time-version-binding) for the application. - Select a [minimum runtime version](#runtime-version-binding). -- Selecting a runtime to run on. ## Select an SDK version -Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK by default. If you've installed the .NET Core 99.9 SDK, the `dotnet` command uses .NET Core SDK 99.9 even when you're targeting .NET Core 2.0 development. Note that this is true for preview versions as well as released versions. +Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK by default. You'll use the .NET Core 99.9 SDK 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 versions. You can target multiple versions of .NET Core on different projects, using the same SDK tools for all projects. +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. When needed, you configure `dotnet` to use a different 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. -`global.json` can be used at different scopes: +`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: + +Search for a global.json file, iteratively navigating the path upward from the current working directory. If a global.json is found: -- Per project, placed beside the project file. -- For a set of projects, placed at a common [grand-]parent for all of the projects. This location can be as high in the directory structure as the root of a drive. +- Use the SDK it specifies if that version is found. +- If the SDK specified in the global.json is not found, roll forward to the latest SDK. +- If no global.json file is found, use the latest SDK The following example shows the `global.json` syntax: ``` json { "sdk": { - "version": "1.0.0" + "version": "2.0.0" } } ``` @@ -75,12 +80,10 @@ You may build your project against multiple frameworks. Setting multiple target netcoreapp2.0;net47 ``` -A given SDK supports a fixed set of frameworks, typically capped to the target framework of the runtimes it includes. 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 will support `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`. +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 will support `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` .NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK is capped to `netstandard2.0`. -A given SDK defines a fixed minimum runtime patch version for each target framework that it supports. The minimum runtime patch version is maintained at the `.0` version (for example, `2.0.0`) for the lifetime of a major/minor runtime version family. - You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example: ``` xml @@ -130,7 +133,7 @@ All NuGet dependencies are resolved as part of the publish operation and reside Developers should remember the following rules: - Runtimes are searched for in the following order (the first found is loaded): - - Highest patch version (check that the minimum runtime path version is satisfied, otherwise error) + - Highest patch version (check that the minimum runtime patch version is satisfied, otherwise error) - Highest minor version - If an acceptable runtime is not found, the application does not run and an error message explains why. @@ -143,22 +146,10 @@ The publishing process will select the latest patch version of the given runtime - The application doesn't specify a hosting environment. - The developer generates a target framework for the application. -The target framework (including the latest instealled security patches) are packaged with the application. +The target framework (including the latest installed security patches) are packaged with the application. It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. ## Publish an application with a specific .NET Core version -`dotnet publish` accepts a version to use for publishing for both self-contained and framework-dependent apps. This is primarily for CI/CD scenarios or other times when you must publish an application, but can't update source code. - -You publish with the latest runtime patch version for the given target framework specifying `--latest`. This argument has the same default runtime binding behavior for publishing self-contained applications. See the following example: - -``` console -dotnet publish -c release -o app --latest -``` - -You publish with a specific runtime patch version for the given target framework specifying `--version=[version]`. It is an error if this version is missing. It's an error if the given version doesn't support the target framework (as a lower bound). You may specify higher versions (even major versions), provided they exist on the machine. You can see this usage in the following example: - -``` console -dotnet publish -c release -o app --version=3.1.0 -``` +`dotnet publish` accepts a version to use for publishing for both self-contained and runtime-dependent apps. This is primarily for CI/CD scenarios or other times when you must publish an application, but can't update source code. From 668b702f95d656c687c3a1a5dd0bd8d4970f1b14 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 27 Jun 2018 16:28:24 -0400 Subject: [PATCH 09/13] rework focus Reworked the focus based on feedback. This should be simpler, more scenario focused, and more clear for users. --- docs/core/versions/binding.md | 84 ++++++++++------------------------- 1 file changed, 23 insertions(+), 61 deletions(-) diff --git a/docs/core/versions/binding.md b/docs/core/versions/binding.md index c639dde3f30c5..031c7ad20ddd6 100644 --- a/docs/core/versions/binding.md +++ b/docs/core/versions/binding.md @@ -3,52 +3,33 @@ title: .NET Core version binding description: Learn How .NET Core finds and chooses runtime versions for your program. author: billwagner ms.author: wiwagn -ms.date: 06/21/2018 +ms.date: 06/27/2018 --- # .NET Core version binding -Rework notes: Keep clear separation between SDK & runtime selection. - - [!INCLUDE [topic-appliesto-net-core-2plus](../../../includes/topic-appliesto-net-core-2plus.md)] -.NET Core provides a single entry-point for operating on projects and built applications with the `dotnet` command. You may have multiple runtime and SDK versions installed. The `dotnet` command must: - -- Select an SDK to use to run an SDK command (for example, with `dotnet new`). -- Select a runtime to target an application (for example, with `dotnet build`). -- Select a runtime to run an application (for example, with `dotnet run`). -- Select a runtime to publish an application (with `dotnet publish`). - -The installation structure is machine global and in the path by default. The structure enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. You may also use private .NET Core installations without use of the path. - -.NET Core applies a set of policies that determines which versions of the .NET Core runtime and SDK are used. The different scenarios and policies are defined in this document. - -These policies perform the following roles: - -- Enable easy and efficient deployment of .NET Core, including security and reliability updates. -- Enable developers to use the latest tools and commands independent of target runtime. - -There are multiple actions where version binding takes place: +This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. These policies provide a balance between always running applications using the specified versions and enabling ease of upgrading both developer and end user machines. These policies perform the following: -- Select an [SDK](#select-an-sdk-version). -- Select a [target framework](#build-time-version-binding) for the application. -- Select a [minimum runtime version](#runtime-version-binding). +- Easy and efficient deployment of .NET Core, including security and reliability updates. +- Usage of the latest tools and commands independent of target runtime. -## Select an SDK version +There are four activities during development and deployment where version binding occurs: -Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK by default. You'll use the .NET Core 99.9 SDK 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. +- 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 Core application](dotnet-run-rolls-forward). +- When you publish a [self-contained application](self-contained-deployments-include-the-selected-runtime). -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. +The rest of this document examines those four scenarios. -When needed, you configure `dotnet` to use a different 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. +## The SDK uses the latest installed version -`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: +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. You'll use the .NET Core 99.9 SDK 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. -Search for a global.json file, iteratively navigating the path upward from the current working directory. If a global.json is found: +On rare occasions, you may need to use a different 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. -- Use the SDK it specifies if that version is found. -- If the SDK specified in the global.json is not found, roll forward to the latest SDK. -- If no global.json file is found, use the latest SDK +`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. The following example shows the `global.json` syntax: @@ -66,7 +47,7 @@ The process for selecting an SDK version is: - `dotnet` uses the SDK specified in the first `global.json` found. - `dotnet` binds to the latest installed SDK if no `global.json` is found. -## Build time version binding +## Target Framework Monikers define build time APIs You build your project against APIs defined in a **Target Framework Moniker** (TFM). You specify the target framework in the project file. Set the `TargetFramework` element in your project file as shown in the following example: @@ -74,13 +55,13 @@ You build your project against APIs defined in a **Target Framework Moniker** (T netcoreapp2.0 ``` -You may build your project against multiple frameworks. 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 will be semicolon-delimited as shown in the following example: +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 will be semicolon-delimited as shown in the following example: ``` xml netcoreapp2.0;net47 ``` -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 will support `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` +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 will support `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` .NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK is capped to `netstandard2.0`. @@ -90,30 +71,20 @@ You can override the minimum runtime patch version (to higher or lower versions) 2.0.4 ``` - The `RuntimeFrameworkVersion` element will override the default version policy if that element is present in the project file. When you target multiple frameworks, you must specify the minimum runtime patch version to the specific target framework, as shown in the following example for .NET Core: + The `RuntimeFrameworkVersion` element overrides the default version policy. When you target multiple frameworks, you must specify the minimum runtime patch version to the specific target framework, as shown in the following example for .NET Core: ``` xml netcoreapp2.0;net47 2.0.4 ``` -A given SDK supports a fixed set of target frameworks. Typically, the target frameworks are the SDK framework version and all earlier versions. - -## Runtime version binding +## dotnet run rolls forward You run an application from source with [`dotnet run`](../tools/dotnet-run.md). `dotnet run` both builds and runs an application. -The built application runs on machines that satisfy the minimum required runtime patch version, stored in the `*.runtimeconfig.json` file. The highest patch version is selected. For example, the `2.0.4` runtime is selected in the case that the minimum runtime version is `2.0.0` while `2.0.0`, `2.0.1` and `2.0.4` are all installed on the machine. This behavior is referred to as "minor version roll-forward." Higher minor or major versions (for example, `2.1.1` or `3.0.1`) won't be considered. Lower versions also won't be considered. When no acceptable runtime is installed, the application will not run. - -Consider an application requiring 2.0.4, `dotnet` would search and bind to a runtime in this order: - -- 2.0.* (highest patch version; ensure that it satisfies 2.0.4 as a lower bound) -- 2.* (highest minor version) - -If neither is found, you see an error message similar to the following example: +The .NET CLI 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. -> This application requires .NET Core 2.0.4. Please install .NET Core 2.0.4 or a higher compatible version. -> Please see https://www.microsoft.com/net/download to learn about .NET Core installation and runtime versioning. +If no acceptable `2.0.*` version is found, a new `2.*` version will be used. For example, if you specified `netcoreapp2.0` and only `2.1.0` is installed, the application will run using the `2.1.0` runtime. This 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 will not run. A few usage examples demonstrate the behavior: @@ -137,19 +108,10 @@ Developers should remember the following rules: - Highest minor version - If an acceptable runtime is not found, the application does not run and an error message explains why. -## Publish a self-contained application +## Self-contained deployments include the selected runtime You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. -The publishing process will select 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, independent of the existence of earlier patch versions or minimum runtime patch version values. The publishing process differs from `dotnet build` runtime selection for two reasons: - -- The application doesn't specify a hosting environment. -- The developer generates a target framework for the application. - -The target framework (including the latest installed security patches) are packaged with the application. +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. It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. - -## Publish an application with a specific .NET Core version - -`dotnet publish` accepts a version to use for publishing for both self-contained and runtime-dependent apps. This is primarily for CI/CD scenarios or other times when you must publish an application, but can't update source code. From 84dc32ce6184b74877e1af8f0b443164c591f74f Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 28 Jun 2018 11:07:53 -0400 Subject: [PATCH 10/13] updated per product team feedback. --- .../versions/{binding.md => selection.md} | 61 ++++++++----------- docs/toc.md | 2 +- 2 files changed, 28 insertions(+), 35 deletions(-) rename docs/core/versions/{binding.md => selection.md} (70%) diff --git a/docs/core/versions/binding.md b/docs/core/versions/selection.md similarity index 70% rename from docs/core/versions/binding.md rename to docs/core/versions/selection.md index 031c7ad20ddd6..8d34f52011148 100644 --- a/docs/core/versions/binding.md +++ b/docs/core/versions/selection.md @@ -1,15 +1,15 @@ --- -title: .NET Core version binding +title: .NET Core version selection description: Learn How .NET Core finds and chooses runtime versions for your program. author: billwagner ms.author: wiwagn ms.date: 06/27/2018 --- -# .NET Core version binding +# .NET Core version selection [!INCLUDE [topic-appliesto-net-core-2plus](../../../includes/topic-appliesto-net-core-2plus.md)] -This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. These policies provide a balance between always running applications using the specified versions and enabling ease of upgrading both developer and end user machines. These policies perform the following: +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: - Easy and efficient deployment of .NET Core, including security and reliability updates. - Usage of the latest tools and commands independent of target runtime. @@ -18,14 +18,14 @@ There are four activities during development and deployment where version bindin - 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 Core application](dotnet-run-rolls-forward). +- When you [run a .NET Core application](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 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. You'll use the .NET Core 99.9 SDK 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. +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. 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. On rare occasions, you may need to use a different 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. @@ -65,33 +65,20 @@ A given SDK supports a fixed set of frameworks, capped to the target framework o .NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK is capped to `netstandard2.0`. -You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example: +## Framework-dependent apps roll forward -``` xml -2.0.4 -``` +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. - The `RuntimeFrameworkVersion` element overrides the default version policy. When you target multiple frameworks, you must specify the minimum runtime patch version to the specific target framework, as shown in the following example for .NET Core: +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. -``` xml -netcoreapp2.0;net47 -2.0.4 -``` - -## dotnet run rolls forward - -You run an application from source with [`dotnet run`](../tools/dotnet-run.md). `dotnet run` both builds and runs an application. - -The .NET CLI 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. - -If no acceptable `2.0.*` version is found, a new `2.*` version will be used. For example, if you specified `netcoreapp2.0` and only `2.1.0` is installed, the application will run using the `2.1.0` runtime. This 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 will not run. +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 will not run. A few usage examples demonstrate the behavior: - 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. -- 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is printed. +- 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is displayed. - 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. -- 2.0.4 is required. No 2.x versions are installed. 3.0.0 is installed. An error message is printed. +- 2.0.4 is required. No 2.x versions are installed. 3.0.0 is installed. An error message is displayed. Minor version roll-forward has one side-effect that may affect end users. Consider the following scenario: @@ -99,19 +86,25 @@ Minor version roll-forward has one side-effect that may affect end users. Consid - 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. - It's possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. -All NuGet dependencies are resolved as part of the publish operation and reside as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. - -Developers should remember the following rules: - -- Runtimes are searched for in the following order (the first found is loaded): - - Highest patch version (check that the minimum runtime patch version is satisfied, otherwise error) - - Highest minor version -- If an acceptable runtime is not found, the application does not run and an error message explains why. - ## Self-contained deployments include the selected runtime You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. 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. -It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. +It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. For more details see the article on [runtime patch selection](../deploying/runtime-patch-selection.md) in deploying .NET Core applications. + +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: + +``` xml +2.0.4 +``` + +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. + +When you target multiple frameworks, you must specify the minimum runtime patch version to the specific target framework, as shown in the following example for .NET Core: + +``` xml +netcoreapp2.0;net47 +2.0.4 +``` diff --git a/docs/toc.md b/docs/toc.md index 3bd43b4065186..94c0a7a869fd4 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -120,7 +120,7 @@ ### [Unit Testing Published Output](core/testing/unit-testing-published-output.md) ### [Live unit testing .NET Core projects with Visual Studio](/visualstudio/test/live-unit-testing-start) ## [Versioning](core/versions/index.md) -### [.NET Core version binding](core/versions/binding.md) +### [.NET Core version binding](core/versions/selection.md) ## [Runtime IDentifier catalog](core/rid-catalog.md) ## [.NET Core SDK Overview](core/sdk.md) ## [.NET Core CLI Tools](core/tools/index.md) From 211e8e6ae0f8a282585b8e48888f281758d33183 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 28 Jun 2018 17:24:46 -0400 Subject: [PATCH 11/13] fix link --- docs/core/versions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/versions/index.md b/docs/core/versions/index.md index 3bbc830f7aab0..2e785bfed18e7 100644 --- a/docs/core/versions/index.md +++ b/docs/core/versions/index.md @@ -29,7 +29,7 @@ The use of a single version number makes it easier for users to know what versio ### Version binding -.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are fully explored in the article on [binding](binding.md). +.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are fully explored in the article on [binding](selection.md). One can think of these policies performing the following roles: From 4dd19d83f52bc088cb867cff6dc2e286bd25eeea Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 29 Jun 2018 15:37:27 -0400 Subject: [PATCH 12/13] binding -> version Per Product team feedback. --- docs/core/versions/index.md | 4 ++-- docs/core/versions/selection.md | 4 ++-- docs/toc.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/core/versions/index.md b/docs/core/versions/index.md index 2e785bfed18e7..4bd9ef9554fd5 100644 --- a/docs/core/versions/index.md +++ b/docs/core/versions/index.md @@ -27,9 +27,9 @@ With .NET Core 2.0, downloads show a single version number in their file name. T The use of a single version number makes it easier for users to know what version of the SDK to install on their dev machines, and what the corresponding version of the shared framework should be when time comes to provision a production environment. When downloading an SDK or runtime, the version number you see is going to be the same. -### Version binding +### Version selection -.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are fully explored in the article on [binding](selection.md). +.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are fully explored in the article on [version selection](selection.md). One can think of these policies performing the following roles: diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 8d34f52011148..5a1e1f7c78b50 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -14,7 +14,7 @@ This article explains the policies used by the .NET Core tools, SDK, and runtime - Easy and efficient deployment of .NET Core, including security and reliability updates. - Usage of the latest tools and commands independent of target runtime. -There are four activities during development and deployment where version binding occurs: +There are four activities during development and deployment where 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). @@ -88,7 +88,7 @@ Minor version roll-forward has one side-effect that may affect end users. Consid ## Self-contained deployments include the selected runtime -You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. +You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime version selection occurs at publishing time, not run-time. 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. diff --git a/docs/toc.md b/docs/toc.md index 94c0a7a869fd4..4b3ae9bb32e9a 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -120,7 +120,7 @@ ### [Unit Testing Published Output](core/testing/unit-testing-published-output.md) ### [Live unit testing .NET Core projects with Visual Studio](/visualstudio/test/live-unit-testing-start) ## [Versioning](core/versions/index.md) -### [.NET Core version binding](core/versions/selection.md) +### [.NET Core version selection](core/versions/selection.md) ## [Runtime IDentifier catalog](core/rid-catalog.md) ## [.NET Core SDK Overview](core/sdk.md) ## [.NET Core CLI Tools](core/tools/index.md) From 9fd3e15e77ace5292ddf11911072851ee5498946 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 3 Jul 2018 13:04:27 -0400 Subject: [PATCH 13/13] update per feedback. This can get added back later, once #4704 is approved. --- docs/core/deploying/index.md | 2 +- docs/core/versions/index.md | 2 +- docs/core/versions/selection.md | 60 +++++++++++++++------------------ 3 files changed, 30 insertions(+), 34 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index bad579a37469b..b87f76368bfd7 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -36,7 +36,7 @@ There are also a few disadvantages: ## Self-contained deployments (SCD) -For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. For more information on version binding at runtime see the topic on [version binding in .NET Core](../versions/binding.md) +For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. For more information on version binding at runtime, see the article on [version binding in .NET Core](../versions/selection.md) FDD and SCD deployments use separate host executables, so you can sign a host executable for an SCD with your publisher signature. diff --git a/docs/core/versions/index.md b/docs/core/versions/index.md index 4bd9ef9554fd5..92b7dd83a473f 100644 --- a/docs/core/versions/index.md +++ b/docs/core/versions/index.md @@ -31,7 +31,7 @@ The use of a single version number makes it easier for users to know what versio .NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are fully explored in the article on [version selection](selection.md). -One can think of these policies performing the following roles: +You can think of these policies as performing the following roles: * Enable easy and efficient deployment of .NET Core, including security and reliability updates. * Enable developers to use the latest tools and commands independent of target runtime. diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 5a1e1f7c78b50..c5b1434b89664 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -1,6 +1,6 @@ --- title: .NET Core version selection -description: Learn How .NET Core finds and chooses runtime versions for your program. +description: Learn how .NET Core finds and chooses runtime versions for your program. author: billwagner ms.author: wiwagn ms.date: 06/27/2018 @@ -12,26 +12,26 @@ ms.date: 06/27/2018 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: - Easy and efficient deployment of .NET Core, including security and reliability updates. -- Usage of the latest tools and commands independent of target runtime. +- Use the latest tools and commands independent of target runtime. -There are four activities during development and deployment where version selection occurs: +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 Core application](framework-dependent-apps-roll-forward). -- When you publish a [self-contained application](self-contained-deployments-include-the-selected-runtime). +- When you run an SDK command, [the sdk uses the latest installed version](#the-sdk-uses-the-latest-installed-version). +- When you build an assembly, [target framework monikers define build time APIs](#target-framework-monikers-define-build-time-apis). +- When you run a .NET Core application, [target framework dependent apps roll forward](#framework-dependent-apps-roll-forward). +- When you publish a self-contained application, [self-contained deployments include the selected runtime](#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 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. 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. +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. -On rare occasions, you may need to use a different 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. +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. -`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. +*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. -The following example shows the `global.json` syntax: +The following example shows the *global.json* syntax: ``` json { @@ -43,56 +43,59 @@ The following example shows the `global.json` syntax: The process for selecting an SDK version is: -- `dotnet` searches for a `global.json` file iteratively reverse-navigating the path upward from the current working directory. -- `dotnet` uses the SDK specified in the first `global.json` found. -- `dotnet` binds to the latest installed SDK if no `global.json` is found. +1. `dotnet` searches for a *global.json* file iteratively reverse-navigating the path upward from the current working directory. +1. `dotnet` uses the SDK specified in the first *global.json* found. +1. `dotnet` binds to the latest installed SDK if no *global.json* is found. + +You can learn more about selecting an SDK version in the [matching rules](../tools/global-json.md) section of the topic on *global.json*. ## Target Framework Monikers define build time APIs -You build your project against APIs defined in a **Target Framework Moniker** (TFM). You specify the target framework in the project file. Set the `TargetFramework` element in your project file as shown in the following example: +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: ``` xml netcoreapp2.0 ``` -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 will be semicolon-delimited as shown in the following example: +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: ``` xml netcoreapp2.0;net47 ``` -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 will support `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` +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`. -.NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK is capped to `netstandard2.0`. +.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`. ## Framework-dependent apps roll forward -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. +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. 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. -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 will not run. +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. A few usage examples demonstrate the behavior: -- 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. +- 2.0.4 is required. 2.0.5 is the highest patch version installed. 2.0.5 is used. - 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is displayed. +- 2.04 is required. 2.0.0 is the latest version installed. An error message is displayed. - 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. -- 2.0.4 is required. No 2.x versions are installed. 3.0.0 is installed. An error message is displayed. +- 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. Minor version roll-forward has one side-effect that may affect end users. Consider the following scenario: - 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is installed. 2.2.2 is used. -- 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. +- 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. - It's possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. ## Self-contained deployments include the selected runtime -You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime version selection occurs at publishing time, not run-time. +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. 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. -It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. For more details see the article on [runtime patch selection](../deploying/runtime-patch-selection.md) in deploying .NET Core applications. +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. 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,10 +104,3 @@ Self-contained deployments may require a specific patch version. You can overrid ``` 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. - -When you target multiple frameworks, you must specify the minimum runtime patch version to the specific target framework, as shown in the following example for .NET Core: - -``` xml -netcoreapp2.0;net47 -2.0.4 -```