Merge pull request #6304 from dotnet/master

Update Live with current Master

Author: BillWagner

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/get-started.md

@@ -1,51 +1,82 @@
 ---
 title: Get started with .NET Core
 description: Find resources to learn how to build .NET Core applications on Windows, Linux and macOS.
-author: johalex
-ms.author: johalex
-ms.date: 09/14/2017
+author: thraka
+ms.author: adegeo
+ms.date: 06/27/2018
 ---
+
 # Get started with .NET Core
 
-.NET Core runs on [Windows](#windows), [Linux](#linux), and [macOS / OS X](#os-x--macos).
+This article provides information on getting started with .NET Core. .NET Core can be installed on Windows, Linux, and macOS. You can code in your favorite text editor and produce cross-platform libraries and applications. 
+
+If you're unsure what .NET Core is, or how it relates to other .NET technologies, start with the [What is .NET](https://www.microsoft.com/net/learn/what-is-dotnet) overview. Put simply, .NET Core is an open-source, cross-platform, implementation of .NET.
+
+## Create an application
+
+First, download and install the [.NET Core SDK](https://www.microsoft.com/net/download/) on your computer.
+
+Next, open a terminal such as **PowerShell**, **Command Prompt**, or **bash**. Type the following `dotnet` commands to create and run a C# application.
+
+```console
+dotnet new console --output sample1
+dotnet run --project sample1
+```
+
+You should see the following output:
+
+```console
+Hello World!
+```
+
+Congratulations! You've created a simple .NET Core application. You can also use [Visual Studio Code](tutorials/with-visual-studio-code.md), [Visual Studio 2017](tutorials/with-visual-studio.md) (Windows only), or [Visual Studio for Mac](tutorials/using-on-mac-vs.md) (macOS only), to create a .NET Core application.
+
+## Tutorials
+
+You can get started developing .NET Core applications by following these step-by-step tutorials.
+
+# [Windows](#tab/windows)
+
+* [Build a C# "Hello World" Application with .NET Core in Visual Studio 2017.](./tutorials/with-visual-studio.md)
+
+* [Build a C# class library with .NET Core in Visual Studio 2017.](./tutorials/library-with-visual-studio.md)
+
+* [Build a Visual Basic "Hello World" application with .NET Core in Visual Studio 2017.](./tutorials/vb-with-visual-studio.md)
+
+* [Build a class library with Visual Basic and .NET Core in Visual Studio 2017.](./tutorials/vb-library-with-visual-studio.md)  
+
+* Watch a video on [how to install and use Visual Studio Code and .NET Core](https://channel9.msdn.com/Blogs/dotnet/Get-started-with-VS-Code-using-CSharp-and-NET-Core/).
+
+* Watch a video on [how to install and use Visual Studio 2017 and .NET Core](https://channel9.msdn.com/Blogs/dotnet/Get-Started-NET-Core-Visual-Studio-2017/).
+
+* [Getting started with .NET Core using the command-line.](tutorials/using-with-xplat-cli.md)
 
-## Windows
+See the [Prerequisites for Windows development](windows-prerequisites.md) article for a list of the supported Windows versions.
 
-Install .NET Core on [Windows](https://www.microsoft.com/net/core#windows). 
+# [Linux](#tab/linux)
 
-You can get started developing .NET Core apps by following these step-by-step tutorials.
+You can get started developing .NET Core application by following these step-by-step tutorials.
 
-* [Building a C# Hello World Application with .NET Core in Visual Studio 2017](./tutorials/with-visual-studio.md) - Learn to build, debug, and publish a simple .NET Core console application using C# and Visual Studio 2017.
-* [Building a class library with C# and .NET Core in Visual Studio 2017](./tutorials/library-with-visual-studio.md) - Learn how to build a class library written in C# using Visual Studio 2017.
-* [Build a Visual Basic Hello World application with .NET Core in Visual Studio 2017](./tutorials/vb-with-visual-studio.md) - Learn to build, debug, and publish a simple .NET Core console application using Visual Basic and Visual Studio 2017. 
-* [Build a class library with Visual Basic and .NET Core in Visual Studio 2017](./tutorials/vb-library-with-visual-studio.md) - Learn how to build a class library written in Visual Basic using Visual Studio 2017.
-* [Get started with Visual Studio Code using C# and .NET Core on Windows](https://channel9.msdn.com/Blogs/dotnet/Get-started-with-VS-Code-using-CSharp-and-NET-Core) - This [Channel9](https://channel9.msdn.com) video shows you how to install and use [Visual Studio Code](https://code.visualstudio.com/), Microsoft's lightweight cross-platform code editor, to create your first console application in .NET Core.
-* [Get Started with .NET Core and Visual Studio 2017](https://channel9.msdn.com/Blogs/dotnet/Get-Started-NET-Core-Visual-Studio-2017) - This [Channel9](https://channel9.msdn.com) video shows you how to install and use [Visual Studio 2017](https://aka.ms/vsdownload?utm_source=mscom&utm_campaign=msdocs), Microsoft's fully-featured IDE, to create your first cross-platform console application in .NET Core.
-* [Getting started with .NET Core using the command-line](tutorials/using-with-xplat-cli.md) - Use any code editor with the [.NET Core cross-platform command-line interface (CLI)](tools/index.md).
+* [Getting started with .NET Core using the command-line.](tutorials/using-with-xplat-cli.md)
 
-See the [Prerequisites for Windows development](windows-prerequisites.md) topic for a list of the supported Windows versions.
+* Watch a video on [getting started with Visual Studio Code using C# and .NET Core on Ubuntu](https://channel9.msdn.com/Blogs/dotnet/Get-started-with-VS-Code-Csharp-dotnet-Core-Ubuntu).
 
-## Linux
+See the [Prerequisites for Linux development](linux-prerequisites.md) article for a list of the supported Linux distros and versions.
 
-Install .NET Core on [Linux](https://www.microsoft.com/net/core#linuxredhat).
+# [macOS](#tab/macos)
 
-You can get started developing .NET Core apps by following these step-by-step tutorials.
+You can get started developing .NET Core application by following these step-by-step tutorials.
 
-* [Getting started with .NET Core using the command-line](tutorials/using-with-xplat-cli.md) - Use any code editor with the [.NET Core cross-platform command-line interface (CLI)](tools/index.md).
-* [Get started with Visual Studio Code using C# and .NET Core on Ubuntu](https://channel9.msdn.com/Blogs/dotnet/Get-started-with-VS-Code-Csharp-dotnet-Core-Ubuntu) - This [Channel9](https://channel9.msdn.com) video shows you how to install and use [Visual Studio Code](https://code.visualstudio.com/), Microsoft's lightweight cross-platform code editor, to create your first console application in .NET Core on Ubuntu 14.04.
+* Watch a video on [Getting started with Visual Studio Code using C# and .NET Core on macOS](https://channel9.msdn.com/Blogs/dotnet/Get-started-VSCode-NET-Core-Mac).
 
-See the [Prerequisites for Linux development](linux-prerequisites.md) topic for a list of the supported Linux distros and versions.
+* [Getting started with .NET Core on macOS, using Visual Studio Code.](tutorials/using-on-macos.md)
 
-## OS X / macOS
+* [Getting started with .NET Core using the command-line.](tutorials/using-with-xplat-cli.md)
 
-Install .NET Core for [macOS](https://www.microsoft.com/net/core#macos). .NET Core is supported on OS X El Capitan (version 10.11) and macOS Sierra (version 10.12).
+* [Getting started with .NET Core on macOS using Visual Studio for Mac.](tutorials/using-on-mac-vs.md)
 
-You can get started developing .NET Core apps by following these step-by-step tutorials.
+* [Build a complete .NET Core solution on macOS using Visual Studio for Mac.](tutorials/using-on-mac-vs-full-solution.md)
 
-* [Get started with Visual Studio Code using C# and .NET Core on macOS](https://channel9.msdn.com/Blogs/dotnet/Get-started-VSCode-NET-Core-Mac) - This [Channel9](https://channel9.msdn.com) video shows you how to install and use [Visual Studio Code](https://code.visualstudio.com/), Microsoft's lightweight cross-platform code editor, to create your first console application in .NET Core. 
-* [Getting started with .NET Core on macOS, using Visual Studio Code](tutorials/using-on-macos.md) - A tour of the steps and workflow to create a .NET Core Solution using Visual Studio Code that includes unit tests, third-party libraries and how to use the debugging tools.
-* [Getting started with .NET Core using the command-line](tutorials/using-with-xplat-cli.md) - Use any code editor with the [.NET Core cross-platform command-line interface (CLI)](tools/index.md).
-* [Getting started with .NET Core on macOS using Visual Studio for Mac](tutorials/using-on-mac-vs.md) - This tutorial shows you how to build a simple .NET Core console application using Visual Studio for Mac.
-* [Building a complete .NET Core solution on macOS using Visual Studio for Mac](tutorials/using-on-mac-vs-full-solution.md) - This tutorial shows you how to build a complete .NET Core solution that includes a reusable library and unit testing.
+See the [Prerequisites for macOS development](macos-prerequisites.md) article for a list of the supported OS X / macOS versions.
 
-See the [Prerequisites for macOS development](macos-prerequisites.md) topic for a list of the supported OS X / macOS versions.
+***

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.