Merge pull request #4949 from dotnet/master

Update live with current master

Author: mairaw

docs/csharp/tutorials/console-teleprompter.md

@@ -14,49 +14,50 @@ ms.assetid: 883cd93d-50ce-4144-b7c9-2df28d9c11a0
 
 # Console Application
 
-## Introduction
 This tutorial teaches you a number of features in .NET Core and the C# language. You’ll learn:
-*	The basics of the .NET Core Command Line Interface (CLI)
-*	The structure of a C# Console Application
-*	Console I/O
-*	The basics of File I/O APIs in .NET Core
-*	The basics of the Task Asynchronous Programming Model in .NET Core
+
+- The basics of the .NET Core Command Line Interface (CLI)
+- The structure of a C# Console Application
+- Console I/O
+- The basics of File I/O APIs in .NET
+- The basics of the Task-based Asynchronous Programming in .NET
 
 You’ll build an application that reads a text file, and echoes the
-contents of that text file to the console. The output to the console will
-be paced to match reading it aloud. You can speed up or slow down the pace
+contents of that text file to the console. The output to the console is paced to match reading it aloud. You can speed up or slow down the pace
 by pressing the ‘<’ or ‘>’ keys.
 
-There are a lot of features in this tutorial. Let’s build them one by one. 
+There are a lot of features in this tutorial. Let’s build them one by one.
+
 ## Prerequisites
-You’ll need to setup your machine to run .NET core. You can find the
+
+You’ll need to setup your machine to run .NET Core. You can find the
 installation instructions on the [.NET Core](https://www.microsoft.com/net/core)
 page. You can run this
-application on Windows, Linux, macOS or in a Docker container. 
-You’ll need to install your favorite code editor. 
+application on Windows, Linux, macOS or in a Docker container.
+You’ll need to install your favorite code editor.
+
 ## Create the Application
+
 The first step is to create a new application. Open a command prompt and
 create a new directory for your application. Make that the current
 directory. Type the command `dotnet new console` at the command prompt. This
 creates the starter files for a basic "Hello World" application.
 
 Before you start making modifications, let’s go through the steps to run
 the simple Hello World application. After creating the application, type
-`dotnet restore` ([see note](#dotnet-restore-note)) at the command prompt. This command runs the NuGet
+`dotnet restore` at the command prompt. This command runs the NuGet
 package restore process. NuGet is a .NET package manager. This command
 downloads any of the missing dependencies for your project. As this is a
 new project, none of the dependencies are in place, so the first run will
 download the .NET Core framework. After this initial step, you will only
-need to run `dotnet restore` ([see note](#dotnet-restore-note)) when you add new dependent packages, or update
-the versions of any of your dependencies. This process also creates the
-project lock file (project.lock.json) in your project directory. This file
-helps to manage the project dependencies. It contains the local location
-of all the project dependencies. You do not need to put the file in source
-control; it will be generated when you run `dotnet restore` ([see note](#dotnet-restore-note)). 
+need to run `dotnet restore` when you add new dependent packages, or update
+the versions of any of your dependencies.
+
+[!INCLUDE[DotNet Restore Note](~/includes/dotnet-restore-note.md)]
 
 After restoring packages, you run `dotnet build`. This executes the build
 engine and creates your application executable. Finally, you execute `dotnet run` to
-run your application.  
+run your application.
 
 The simple Hello World application code is all in Program.cs. Open that
 file with your favorite text editor. We’re about to make our first changes.
@@ -68,19 +69,19 @@ using System;
 
 This statement tells the compiler that any types from the `System` namespace
 are in scope. Like other Object Oriented languages you may have used, C#
-uses namespaces to organize types. This hello world program is no
-different. You can see that the program is enclosed in the
-`ConsoleApplication` namespace. That’s not a very descriptive name, so
-change it to `TeleprompterConsole`:
+uses namespaces to organize types. This Hello World program is no
+different. You can see that the program is enclosed in the namespace with the name 
+based on the name of the current directory. For this tutorial, let's change the name of the namespace to `TeleprompterConsole`:
 
 ```csharp
 namespace TeleprompterConsole
 ```
 
 ## Reading and Echoing the File
+
 The first feature to add is the ability to read a text file and display all that text to the console. First, let’s add a text file. Copy the [sampleQuotes.txt](https://github.com/dotnet/samples/raw/master/csharp/getting-started/console-teleprompter/sampleQuotes.txt) file from the GitHub repository for this [sample](https://github.com/dotnet/samples/tree/master/csharp/getting-started/console-teleprompter) into your project directory. This will serve as the script for your application. If you would like information on how to download the sample app for this topic, see the instructions in the [Samples and Tutorials](../../samples-and-tutorials/index.md#viewing-and-downloading-samples) topic.
 
-Next, add the following method in your Program class (right below the `Main` method):
+Next, add the following method in your `Program` class (right below the `Main` method):
 
 ```csharp
 static IEnumerable<string> ReadFrom(string file)
@@ -96,61 +97,61 @@ static IEnumerable<string> ReadFrom(string file)
 }
 ```
 
-This method uses types from two new namespaces. For this to compile you’ll 
+This method uses types from two new namespaces. For this to compile you’ll
 need to add the following two lines to the top of the file:
 
 ```csharp
 using System.Collections.Generic;
 using System.IO;
 ```
 
-The `IEnumerable<T>` interface is defined in the 
-`System.Collections.Generic` namespace. The <xref:System.IO.File> class is defined in the
-`System.IO` namespace.
+The <xref:System.Collections.Generic.IEnumerable%601> interface is defined in the
+<xref:System.Collections.Generic> namespace. The <xref:System.IO.File> class is defined in the <xref:System.IO> namespace.
 
-This method is a special type of C# method called an *Enumerator method*. 
+This method is a special type of C# method called an *Iterator method*. 
 Enumerator methods return sequences that are evaluated lazily. That means 
 each item in the sequence is generated as it is requested by the code 
 consuming the sequence. Enumerator methods are methods that contain one or 
-more `yield return` statements. The object returned by the `ReadFrom` 
+more [`yield return`](../language-reference/keywords/yield.md) statements. The object returned by the `ReadFrom` 
 method contains the code to generate each item in the sequence. In this 
 example, that involves reading the next line of text from the source file, 
 and returning that string. Each time the calling code requests the next 
 item from the sequence, the code reads the next line of text from the file
-and returns it. When the file has been completely read, the sequence 
+and returns it. When the file is completely read, the sequence 
 indicates that there are no more items.
 
-There are two other C# syntax elements that may be new to you. The `using` 
+There are two other C# syntax elements that may be new to you. The [`using`](../language-reference/keywords/using-statement.md) 
 statement in this method manages resource cleanup. The variable that is
 initialized in the `using` statement (`reader`, in this example) must
-implement the `IDisposable` interface. The <xref:System.IDisposable> interface
+implement the <xref:System.IDisposable> interface. That interface
 defines a single method, `Dispose`, that should be called when the
 resource should be released. The compiler generates that call when
 execution reaches the closing brace of the `using` statement. The
 compiler-generated code ensures that the resource is released even if an
 exception is thrown from the code in the block defined by the using
 statement.
 
-The `reader` variable is defined using the `var` keyword. `var` defines an
+The `reader` variable is defined using the `var` keyword. [`var`](../language-reference/keywords/var.md) defines an
 *implicitly typed local variable*. That means the type of the variable is
-determined by the compile time type of the object assigned to the
+determined by the compile-time type of the object assigned to the
 variable. Here, that is the return value from the <xref:System.IO.File.OpenText(System.String)> method, which is
 a <xref:System.IO.StreamReader> object.
- 
-Now, let’s fill in the code to read the file in the `Main` method: 
+
+Now, let’s fill in the code to read the file in the `Main` method:
 
 ```csharp
 var lines = ReadFrom("sampleQuotes.txt");
 foreach (var line in lines)
 {
-    Console.WriteLine(line); 
+    Console.WriteLine(line);
 }
 ```
 
-Run the program (using `dotnet run` and you can see every line printed out
-to the console).  
+Run the program (using `dotnet run`) and you can see every line printed out
+to the console.
 
 ## Adding Delays and Formatting output
+
 What you have is being displayed far too fast to read aloud. Now you need
 to add the delays in the output. As you start, you’ll be building some of
 the core code that enables asynchronous processing. However, these first
@@ -188,7 +189,7 @@ if (!string.IsNullOrWhiteSpace(line))
 }
 ```
 
-The `Task` class is in the `System.Threading.Tasks` namespace, so you need
+The <xref:System.Threading.Tasks.Task> class is in the <xref:System.Threading.Tasks> namespace, so you need
 to add that `using` statement at the top of file:
 
 ```csharp
@@ -202,12 +203,12 @@ issues because the source text file has several lines that have more than
 scrolling by. That’s easy to fix. You’ll just keep track of the length of
 each line, and generate a new line whenever the line length reaches a
 certain threshold. Declare a local variable after the declaration of
-`words` that holds the line length:
+`words` in the `ReadFrom` method that holds the line length:
 
 ```csharp
 var lineLength = 0;
 ```
- 
+
 Then, add the following code after the `yield return word + " ";` statement
 (before the closing brace):
 
@@ -219,11 +220,12 @@ if (lineLength > 70)
     lineLength = 0;
 }
 ```
- 
+
 Run the sample, and you’ll be able to read aloud at its pre-configured
 pace.
 
 ## Async Tasks
+
 In this final step, you’ll add the code to write the output asynchronously
 in one task, while also running another task to read input from the user
 if they want to speed up or slow down the text display. This has a few
@@ -238,10 +240,10 @@ Add this method to your `Program` class (it’s taken from the body of your
 private static async Task ShowTeleprompter()
 {
     var words = ReadFrom("sampleQuotes.txt");
-    foreach (var line in words)
+    foreach (var word in words)
     {
-        Console.Write(line);
-        if (!string.IsNullOrWhiteSpace(line))
+        Console.Write(word);
+        if (!string.IsNullOrWhiteSpace(word))
         {
             await Task.Delay(200);
         }
@@ -274,6 +276,9 @@ in a console application’s `Main` method, you cannot use the `await`
 operator. That would result in the application exiting before all tasks
 have completed.
 
+> [!NOTE]
+> If you use C# 7.1 or later, you can create console applications with [`async` `Main` method](../whats-new/csharp-7-1.md#async-main).
+
 Next, you need to write the second asynchronous method to read from the
 Console and watch for the ‘<’ and ‘>’ keys. Here’s the method you add for
 that task:
@@ -309,10 +314,10 @@ To finish this feature, you need to create a new `async Task` returning
 method that starts both of these tasks (`GetInput` and 
 `ShowTeleprompter`), and also manages the shared data between these two
 tasks.
- 
+
 It’s time to create a class that can handle the shared data between these
 two tasks. This class contains two public properties: the delay, and a
-flag to indicate that the file has been completely read:
+flag `Done` to indicate that the file has been completely read:
 
 ```csharp
 namespace TeleprompterConsole
@@ -331,22 +336,29 @@ namespace TeleprompterConsole
                 DelayInMilliseconds = newDelay;
             }
         }
+
+        public bool Done { get; private set; }
+
+        public void SetDone()
+        {
+            Done = true;
+        }
     }
 }
 ```
 
 Put that class in a new file, and enclose that class in the
 `TeleprompterConsole` namespace as shown above. You’ll also need to add a `using static`
-statement so that you can reference the `Min` and `Max` method without the
-enclosing class or namespace names. A `using static` statement imports the
+statement so that you can reference the `Min` and `Max` methods without the
+enclosing class or namespace names. A [`using static`](../language-reference/keywords/using-static.md) statement imports the
 methods from one class. This is in contrast with the `using` statements used
 up to this point that have imported all classes from a namespace.
 
 ```csharp
 using static System.Math;
 ```
 
-The other language feature that’s new is the `lock` statement. This
+The other language feature that’s new is the [`lock`](../language-reference/keywords/lock-statement.md) statement. This
 statement ensures that only a single thread can be in that code at any
 given time. If one thread is in the locked section, other threads must
 wait for the first thread to exit that section. The `lock` statement uses an
@@ -391,7 +403,6 @@ private static async Task ShowTeleprompter(TelePrompterConfig config)
 
 private static async Task GetInput(TelePrompterConfig config)
 {
-
     Action work = () =>
     {
         do {
@@ -414,28 +425,14 @@ This new version of `ShowTeleprompter` calls a new method in the
 RunTeleprompter().Wait();
 ```
 
-To finish, you'll need to add the
-`SetDone` method, and the `Done` property to the `TelePrompterConfig` class:
-
-```csharp
-public bool Done => done;
-
-private bool done;
-
-public void SetDone()
-{
-    done = true;    
-}
-```
-
 ## Conclusion
+
 This tutorial showed you a number of the features around the C# language
 and the .NET Core libraries related to working in Console applications.
 You can build on this knowledge to explore more about the language, and
 the classes introduced here. You’ve seen the basics of File and Console
-I/O, blocking and non-blocking use of the Task based Asynchronous
-programming model, a tour of the C# language and how C# programs are
+I/O, blocking and non-blocking use of the Task-based asynchronous
+programming, a tour of the C# language and how C# programs are
 organized and the .NET Core Command Line Interface and tools.
- 
-<a name="dotnet-restore-note"></a>
-[!INCLUDE[DotNet Restore Note](~/includes/dotnet-restore-note.md)]
+
+For more information about File I/O, see the [File and Stream I/O](../../standard/io/index.md) topic. For more information about asynchronous programming model used in this tutorial, see the [Task-based Asynchronous Programming](../..//standard/parallel-programming/task-based-asynchronous-programming.md) topic and the [Asynchronous programming](../async.md) topic.

docs/framework/migration-guide/net-framework-4-migration-issues.md

@@ -10,7 +10,7 @@ helpviewer_keywords:
   - "application compatibility"
 ms.assetid: df478548-8c05-4de2-8ba7-adcdbe1c2a60
 author: "rpetrusha"
-ms.author: "mariaw"
+ms.author: "ronpet"
 manager: "wpickett"
 ms.workload: 
   - "mariaw"