Merge pull request #5844 from dotnet/master

Update Live with current Master

Author: mairaw

docs/core/docker/building-net-docker-images.md

@@ -42,7 +42,7 @@ When developing, building, and running containerized applications, we have diffe
     * .js and .css files
 
 
-The reason to include the `dotnet publish` command output in your production image is to keep its' size to a minimum.
+The reason to include the `dotnet publish` command output in your production image is to keep its size to a minimum.
 
 Some .NET Core images share layers between different tags so downloading the latest tag is a relatively lightweight process. If you already have an older version on your machine, this architecture decreases the needed disk space.
 

docs/core/tutorials/consuming-library-with-visual-studio.md

@@ -1,17 +1,17 @@
 ---
-title: Consuming a class library with .NET Core in Visual Studio 2017
+title: Consuming a .NET Standard library in Visual Studio 2017
 description: Learn how to call the members in a class library with Visual Studio 2017.
 author: BillWagner
 ms.author: wiwagn
-ms.date: 08/07/2017
+ms.date: 06/05/2018
 dev_langs: 
   - "csharp"
   - "vb"
 ---
 
-# Consuming a class library with .NET Core in Visual Studio 2017
+# Consuming a .NET Standard library in Visual Studio 2017
 
-Once you've created a class library by following the steps in [Building a C# class library with .NET Core in Visual Studio 2017](./library-with-visual-studio.md) or [Building a Visual Basic class library with .NET Core in Visual Studio 2017](vb-library-with-visual-studio.md), tested it in [Testing a class library with .NET Core in Visual Studio 2017](testing-library-with-visual-studio.md), and built a Release version of the library, the next step is to make it available to callers. You can do this in two ways:
+Once you've created a .NET Standard class library by following the steps in [Building a C# class library with .NET Core in Visual Studio 2017](./library-with-visual-studio.md) or [Building a Visual Basic class library with .NET Core in Visual Studio 2017](vb-library-with-visual-studio.md), tested it in [Testing a class library with .NET Core in Visual Studio 2017](testing-library-with-visual-studio.md), and built a Release version of the library, the next step is to make it available to callers. You can do this in two ways:
 
 * If the library will be used by a single solution (for example, if it's a component in a single large application), you can include it as a project in your solution.
 
@@ -44,7 +44,7 @@ Just as you included unit tests in the same solution as your class library, you
 
    [!CODE-csharp[UsingClassLib#1](../../../samples/snippets/csharp/getting_started/with_visual_studio_2017/showcase.cs)]
 
-   The code uses the [Console.WindowHeight](xref:System.Console.WindowHeight) property to determine the number of rows in the console window. Whenever the [Console.CursorTop](xref:System.Console.CursorTop) property is greater than or equal to the number of rows in the console window, the code clears the console window and displays a message to the user.
+   The code uses the `row` variable to maintain a count of the number of rows of data written to the console window. Whenever it is greater than or equal to 25, the code clears the console window and displays a message to the user.
 
    The program prompts the user to enter a string. It indicates whether the string starts with an uppercase character. If the user presses the Enter key without entering a string, the application terminates, and the console window closes.
 
@@ -74,7 +74,7 @@ Just as you included unit tests in the same solution as your class library, you
 
     [!CODE-vb[UsingClassLib#1](../../../samples/snippets/core/tutorials/vb-library-with-visual-studio/showcase.vb)]
 
-   The code uses the [Console.WindowHeight](xref:System.Console.WindowHeight) property to determine the number of rows in the console window. Whenever the [Console.CursorTop](xref:System.Console.CursorTop) property is greater than or equal to the number of rows in the console window, the code clears the console window and displays a message to the user.
+   The code uses the `row` variable to maintain a count of the number of rows of data written to the console window. Whenever it is greater than or equal to 25, the code clears the console window and displays a message to the user.
 
    The program prompts the user to enter a string. It indicates whether the string starts with an uppercase character. If the user presses the Enter key without entering a string, the application terminates, and the console window closes.
 

docs/core/whats-new/dotnet-core-2-1.md

@@ -3,7 +3,7 @@ title: What's new in .NET Core 2.1
 description: Learn about the new features found in .NET Core 2.1.
 author: rpetrusha
 ms.author: ronpet
-ms.date: 05/30/2018
+ms.date: 06/06/2018
 ---
 # What's new in .NET Core 2.1
 
@@ -13,12 +13,12 @@ ms.date: 05/30/2018
 - [Roll forward](#roll-forward)
 - [Deployment](#deployment)
 - [Windows Compatibility Pack](#windows-compatibility-pack)
-- [JIT compiler improvements](#jit-compiler-improvements)
+- [JIT compilation improvements](#jit-compiler-improvements)
 - [API changes](#api-changes)
 
 ## Tooling
 
-The .NET Core 2.1.300 SDK, the tooling included with .NET Core 2.1, includes the following changes and enhancements:
+The .NET Core 2.1 SDK (v 2.1.300), the tooling included with .NET Core 2.1, includes the following changes and enhancements:
 
 ### Build performance improvements
 
@@ -43,7 +43,9 @@ A number of tools that were available only on a per project basis using [`Dotnet
    ```console
    dotnet watch -- --verbose build
    ```
-
+  
+   Note the `--` option that precedes the `--verbose` option. It delimits the options passed directly to the `dotnet watch` command from the arguments that are passed to the child `dotnet` process. Without it, the `--verbose` option applies to the `dotnet watch` command, not the `dotnet build` command.
+  
    For more information, see [Develop ASP.NET Core apps using dotnet watch](/aspnet/core/tutorials/dotnet-watch)
 
 - `dotnet dev-certs` generates and manages certificates used during development in ASP.NET Core applications.
@@ -66,26 +68,30 @@ dotnet tool install -g dotnetsay
 
 Once installed, the tool can be run from the command line by specifying the tool name. For more information, see [.NET Core Global Tools overview](../tools/global-tools.md).
 
-### Single-source tool management with the `dotnet tool` command
+### Tool management with the `dotnet tool` command
+
+In .NET Core SDK 2.1 (v 2.1.300), all tools operations use the `dotnet tool` command. The following options are available:
 
-In .NET Core 2.1, all tools operations use the `dotnet tool` command. The following options are available:
+- [`dotnet tool install`](../tools/dotnet-tool-install.md) to install a tool.
 
-- `dotnet tool install` to install a tool.
+- [`dotnet tool update`](../tools/dotnet-tool-update.md) to uninstall and reinstall a tool, which effectively updates it.
 
-- `dotnet tool update` to uninstall and reinstall a tool, which effectively updates it.
+- [`dotnet tool list`](../tools/dotnet-tool-list.md) to list currently installed tools.
 
-- `dotnet tool list` to list currently installed tools.
+- [`dotnet tool uninstall`](../tools/dotnet-tool-uninstall.md) to uninstall currently installed tools.
 
 ## Roll forward
 
-All .NET Core applications starting with the .NET Core 2.0 automatically roll forward to the latest *minor version* installed on a system. That is, if the .NET Core version that an application was built with is not present, the application runs against the latest installed minor version. In other words, if an application is built with .NET Core 2.0 and .NET Core 2.0 itself is not present on the host system but .NET Core 2.1 is, the application runs with .NET Core 2.1.
+All .NET Core applications starting with the .NET Core 2.0 automatically roll forward to the latest *minor version* installed on a system. 
+
+Starting with .NET Core 2.0, if the version of .NET Core that an application was built with is not present at runtime, the application automatically runs against the latest installed *minor version* of .NET Core. In other words, if an application is built with .NET Core 2.0, and .NET Core 2.0 is not present on the host system but .NET Core 2.1 is, the application runs with .NET Core 2.1.
 
 > [!IMPORTANT]
 > This roll-forward behavior doesn't apply to preview releases. Nor does it apply to major releases. For example, a .NET Core 1.0 application wouldn't roll forward to .NET Core 2.0 or .NET Core 2.1.
 
 You can also disable minor version roll forward in any of three ways:
 
-- Set the `DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX` environment variable equal to 0,
+- Set the `DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX` environment variable to 0.
 
 - Add the following line to the runtimeconfig.json file:
 
@@ -103,31 +109,43 @@ You can also disable minor version roll forward in any of three ways:
 
 ### Self-contained application servicing
 
-`dotnet publish` now publishes self-contained applications with a serviced runtime version. When you publish a self-contained application with the .NET Core 2.1 SDK, your application includes the latest serviced runtime version known by that SDK. When you upgrade to the latest SDK, you’ll publish with the latest .NET Core runtime version. This applies for .NET Core 1.0 runtimes and later.
+`dotnet publish` now publishes self-contained applications with a serviced runtime version. When you publish a self-contained application with the .NET Core 2.1 SDK (v 2.1.300), your application includes the latest serviced runtime version known by that SDK. When you upgrade to the latest SDK, you’ll publish with the latest .NET Core runtime version. This applies for .NET Core 1.0 runtimes and later.
 
 Self-contained publishing relies on runtime versions on NuGet.org. You do not need to have the serviced runtime on your machine.
 
-Using the .NET Core 2.0 SDK, self-contained applications are published with the .NET Core 2.0.0 runtime unless a different version is specified via the `RuntimeFrameworkVersion` property. With this new behavior, you’ll no longer need to set this property to select a higher runtime version for a self-contained application. The easiest approach going forward is to always publish with .NET Core 2.1 SDK.
+Using the .NET Core 2.0 SDK, self-contained applications are published with the .NET Core 2.0.0 runtime unless a different version is specified via the `RuntimeFrameworkVersion` property. With this new behavior, you’ll no longer need to set this property to select a higher runtime version for a self-contained application. The easiest approach going forward is to always publish with .NET Core 2.1 SDK (v 2.1.300).
 
 ## Windows Compatibility Pack
 
 When you port existing code from the .NET Framework to .NET Core, you can use the [Windows Compatibility Pack](https://www.nuget.org/packages/Microsoft.Windows.Compatibility). It provides access to 20,000 more APIs than are available in .NET Core. These APIs include types in the <xref:System.Drawing?displayProperty="nameWithType"> namespace, the <xref:System.Diagnostics.EventLog> class, WMI, Performance Counters, Windows Services, and the Windows registry types and members.
 
 ## JIT compiler improvements
 
-.NET Core incorporates a new JIT compiler technology called *tiered compilation* (also known as *adaptive optimization*) that can significantly improve performance.
+.NET Core incorporates a new JIT compiler technology called *tiered compilation* (also known as *adaptive optimization*) that can significantly improve performance. Tiered compilation is an opt-in setting.
 
 One of the important tasks performed by the JIT compiler is optimizing code execution. For little-used code paths, however, the compiler may spend more time optimizing code than the runtime spends running unoptimized code. Tiered compilation introduces two stages in JIT compilation:
 
 - A **first tier**, which generates code as quickly as possible.
 
 - A **second tier**, which generates optimized code for those methods that are executed frequently. The second tier of compilation is performed in parallel for enhanced performance.
 
-You can test tiered compilation with a .NET Core 2.1 app by setting the following environment variable:
+You can opt into tiered compilation in either of two ways.
 
-```console
-COMPlus_TieredCompilation="1"
-```
+- To use tiered compilation in all projects that use the .NET Core 2.1 SDK, set the following environment variable:
+
+  ```console
+  COMPlus_TieredCompilation="1"
+  ```
+
+- To use tiered compilation on a per-project basis, add the `<TieredCompilation>` property to the `<PropertyGroup>` section of the MSBuild project file, as the following example shows:
+
+   ```xml
+   <PropertyGroup>
+      <!-- other property definitions -->
+
+      <TieredCompilation>true</TieredCompilation>
+   </PropertyGroup>
+   ```
 
 ## API changes
 
@@ -187,16 +205,20 @@ The sockets implementation introduced in .NET Core 2.1 has a number of advantage
 
 - A significant performance improvement when compared with the previous implementation.
 
-- Elimination on platform dependencies, which simplifies deployment and servicing.
+- Elimination of platform dependencies, which simplifies deployment and servicing.
 
 - Consistent behavior across all .NET Core platforms.
 
-Sockets based on <xref:System.Net.Http.SocketsHttpHandler> is the default implementation in .NET Core 2.1. However, you can configure your application to use the older <xref:System.Net.Http.HttpClientHandler> class by calling the <xref:System.AppContext.SetSwitch%2A?displayProperty="nameWithType"> method:
+<xref:System.Net.Http.SocketsHttpHandler> is the default implementation in .NET Core 2.1. However, you can configure your application to use the older <xref:System.Net.Http.HttpClientHandler> class by calling the <xref:System.AppContext.SetSwitch%2A?displayProperty="nameWithType"> method:
 
 ```csharp
 AppContext.SetSwitch("System.Net.Http.useSocketsHttpHandler", false);
 ```
 
+```vb
+AppContext.SetSwitch("System.Net.Http.useSocketsHttpHandler", False)
+```
+
 You can also use an environment variable to opt out of using sockets implementations based on <xref:System.Net.Http.SocketsHttpHandler>. To do this, set the `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` to either `false` or 0.
 
 On Windows, you can also choose to use <xref:System.Net.Http.WinHttpHandler?displayProperty=nameWithType>, which relies on a native implementation, or the <xref:System.Net.Http.SocketsHttpHandler> class by passing an instance of the class to the <xref:System.Net.Http.HttpClient> constructor.

docs/csharp/delegate-class.md

@@ -109,10 +109,8 @@ Suppose you wanted to sort a list of strings by their length. Your
 comparison function might be the following:
 
 ```csharp
-private static int CompareLength(string left, string right)
-{
-    return left.Length.CompareTo(right.Length);
-}
+private static int CompareLength(string left, string right) =>
+    left.Length.CompareTo(right.Length);
 ```
 
 The method is declared as a private method. That's fine. You may not

docs/csharp/delegates-events.md

@@ -41,3 +41,4 @@ This topic will be covered under the following articles:
 
     This article discusses how you should distinguish between using events and delegates in your designs.
 
+You can download the [delegates sample](https://github.com/dotnet/samples/tree/master/csharp/delegates-and-events) and the [events sample](https://github.com/dotnet/samples/tree/master/csharp/events) from our GitHub samples repository.

docs/csharp/delegates-patterns.md

@@ -78,35 +78,18 @@ Let's start small: the initial implementation will accept new messages,
 and write them using any attached delegate. You can start with one delegate
 that writes messages to the console.
 
-```csharp
-public static class Logger
-{
-    public static Action<string> WriteMessage;
-    
-    public static void LogMessage(string msg)
-    {
-        WriteMessage(msg);
-    }
-}
-```
+[!code-csharp[LoggerImplementation](../../samples/csharp/delegates-and-events/Logger.cs#FirstImplementation "A first Logger implementation.")]
 
 The static class above is the simplest thing that can work. We need to
 write the single implementation for the method that writes messages
 to the console: 
 
-```csharp
-public static void LogToConsole(string message)
-{
-    Console.Error.WriteLine(message);
-}
-```
+[!code-csharp[LogToConsole](../../samples/csharp/delegates-and-events/Program.cs#LogToConsole "A Console logger.")]
 
 Finally, you need to hook up the delegate by attaching it to
 the WriteMessage delegate declared in the logger:
 
-```csharp
-Logger.WriteMessage += LogToConsole;
-```
+[!code-csharp[ConnectDelegate](../../samples/csharp/delegates-and-events/Program.cs#ConnectDelegate "Connect to the delegate")]
 
 ## Practices
 
@@ -130,50 +113,14 @@ creating other logging mechanisms.
 Next, let's add a few arguments to the `LogMessage()` method so that
 your log class creates more structured messages:
 
-```csharp
-// Logger implementation two
-public enum Severity
-{
-    Verbose,
-    Trace,
-    Information,
-    Warning,
-    Error,
-    Critical
-}
-
-public static class Logger
-{
-    public static Action<string> WriteMessage;
-    
-    public static void LogMessage(Severity s, string component, string msg)
-    {
-        var outputMsg = $"{DateTime.Now}\t{s}\t{component}\t{msg}";
-        WriteMessage(outputMsg);
-    }
-}
-```
+[!code-csharp[Severity](../../samples/csharp/delegates-and-events/Logger.cs#Severity "Define severities")]
+[!code-csharp[NextLogger](../../samples/csharp/delegates-and-events/Logger.cs#LoggerTwo "Refine the Logger")]
 
 Next, let's make use of that `Severity` argument to filter the messages
 that are sent to the log's output. 
 
-```csharp
-public static class Logger
-{
-    public static Action<string> WriteMessage;
-    
-    public static Severity LogLevel {get;set;} = Severity.Warning;
-    
-    public static void LogMessage(Severity s, string component, string msg)
-    {
-        if (s < LogLevel)
-            return;
-            
-        var outputMsg = $"{DateTime.Now}\t{s}\t{component}\t{msg}";
-        WriteMessage(outputMsg);
-    }
-}
-```
+[!code-csharp[FinalLogger](../../samples/csharp/delegates-and-events/Logger.cs#LoggerFinal "Finish the Logger")]
+
 ## Practices
 
 You've added new features to the logging infrastructure. Because
@@ -198,42 +145,13 @@ each message is generated.
 
 Here is that file based logger:
 
-```csharp
-public class FileLogger
-{
-    private readonly string logPath;
-    public FileLogger(string path)
-    {
-        logPath = path;
-        Logger.WriteMessage += LogMessage;
-    }
-    
-    public void DetachLog() => Logger.WriteMessage -= LogMessage;
-
-    // make sure this can't throw.
-    private void LogMessage(string msg)
-    {
-        try {
-            using (var log = File.AppendText(logPath))
-            {
-                log.WriteLine(msg);
-                log.Flush();
-            }
-        } catch (Exception e)
-        {
-            // Hmm. Not sure what to do.
-            // Logging is failing...
-        }
-    }
-}
-```
+[!code-csharp[FileLogger](../../samples/csharp/delegates-and-events/FileLogger.cs#FileLogger "Log to files")]
+
 
 Once you've created this class, you can instantiate it and it attaches
 its LogMessage method to the Logger component:
 
-```csharp
-var file = new FileLogger("log.txt");
-```
+[!code-csharp[FileLogger](../../samples/csharp/delegates-and-events/Program.cs#FileLogger "Log to files")]
 
 These two are not mutually exclusive. You could attach both log
 methods and generate messages to the console and a file: