Document .Net core version binding

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

docs/core/versions/index.md

@@ -27,6 +27,15 @@ 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 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 [version selection](selection.md).
+
+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.
+
 ### 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.

docs/core/versions/selection.md

@@ -0,0 +1,106 @@
+---
+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 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 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.
+- Use the latest tools and commands independent of target runtime.
+
+Version selection occurs:
+
+- When you run an SDK command, [the sdk uses the latest installed version](#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 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 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.
+
+The following example shows the *global.json* syntax:
+
+``` json
+{
+  "sdk": {
+    "version": "2.0.0"
+  }
+}
+```
+
+The process for selecting an SDK version is:
+
+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](../../standard/frameworks.md) in the project file. Set the `TargetFramework` element in your project file as shown in the following example:
+
+``` xml
+<TargetFramework>netcoreapp2.0</TargetFramework>
+```
+
+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
+<TargetFrameworks>netcoreapp2.0;net47</TargetFrameworks>
+```
+
+A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. For example, the .NET 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 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 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 won't run.
+
+A few usage examples demonstrate the behavior:
+
+- 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 (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. 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 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'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:
+
+``` xml
+<RuntimeFrameworkVersion>2.0.4</RuntimeFrameworkVersion>
+```
+
+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.

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)
-<!--### [🔧 Servicing](core/versions/servicing.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)