Cover async Main language reference

docs/csharp/programming-guide/main-and-command-args/index.md

@@ -1,7 +1,7 @@
 ---
-title: "Main() and Command-Line Arguments (C# Programming Guide)"
+title: "Main() and command-line arguments (C# Programming Guide)"
 
-ms.date: "2015-07-20"
+ms.date: "2017-08-02"
 ms.prod: .net
 
 
@@ -41,39 +41,30 @@ translation.priority.ht:
   - "zh-cn"
   - "zh-tw"
 ---
-# Main() and Command-Line Arguments (C# Programming Guide)
-The `Main` method is the entry point of a C# console application or windows application. (Libraries and services do not require a `Main` method as an entry point.). When the application is started, the `Main` method is the first method that is invoked.  
-
- There can only be one entry point in a C# program. If you have more than one class that has a `Main` method, you must compile your program with the **/main** compiler option to specify which `Main` method to use as the entry point. For more information, see [/main (C# Compiler Options)](../../../csharp/language-reference/compiler-options/main-compiler-option.md).  
-
- [!code-cs[csProgGuideMain#17](../../../csharp/programming-guide/inside-a-program/codesnippet/CSharp/main-and-command-line-arguments_1.cs)]  
-
-## Overview  
-
--   The `Main` method is the entry point of an .exe program; it is where the program control starts and ends.  
-
--   `Main` is declared inside a class or struct. `Main` must be [static](../../../csharp/language-reference/keywords/static.md) and it should not be [public](../../../csharp/language-reference/keywords/public.md). (In the earlier example, it receives the default access of [private](../../../csharp/language-reference/keywords/private.md).) The enclosing class or struct is not required to be static.  
-
--   `Main` can either have a `void` or `int` return type.  
-
--   The `Main` method can be declared with or without a `string[]` parameter that contains command-line arguments. When using [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] to create Windows Forms applications, you can add the parameter manually or else use the <xref:System.Environment> class to obtain the command-line arguments. Parameters are read as zero-indexed command-line arguments. Unlike C and C++, the name of the program is not treated as the first command-line argument.  
-
-## In This Section  
-
--   [Command-Line Arguments](../../../csharp/programming-guide/main-and-command-args/command-line-arguments.md)  
-
--   [How to: Display Command Line Arguments](../../../csharp/programming-guide/main-and-command-args/how-to-display-command-line-arguments.md)  
-
--   [How to: Access Command-Line Arguments Using foreach](../../../csharp/programming-guide/main-and-command-args/how-to-access-command-line-arguments-using-foreach.md)  
-
--   [Main() Return Values](../../../csharp/programming-guide/main-and-command-args/main-return-values.md)  
-
-## C# Language Specification  
- [!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)]  
-
-## See Also  
- [Command-line Building With csc.exe](../../../csharp/language-reference/compiler-options/command-line-building-with-csc-exe.md)   
- [C# Programming Guide](../../../csharp/programming-guide/index.md)   
- [Methods](../../../csharp/programming-guide/classes-and-structs/methods.md)   
- [Inside a C# Program](../../../csharp/programming-guide/inside-a-program/index.md)   
- [\<paveover>C# Sample Applications](http://msdn.microsoft.com/en-us/9a9d7aaa-51d3-4224-b564-95409b0f3e15)
+# Main() and command-line arguments (C# Programming Guide)
+
+The `Main` method is the entry point of a C# application. (Libraries and services do not require a `Main` method as an entry point.) When the application is started, the `Main` method is the first method that is invoked.
+
+ There can only be one entry point in a C# program. If you have more than one class that has a `Main` method, you must compile your program with the **/main** compiler option to specify which `Main` method to use as the entry point. For more information, see [/main (C# Compiler Options)](../../../csharp/language-reference/compiler-options/main-compiler-option.md).
+
+ [!code-cs[csProgGuideMain#17](../../../csharp/programming-guide/inside-a-program/codesnippet/CSharp/main-and-command-line-arguments_1.cs)]
+
+## Overview
+
+- The `Main` method is the entry point of an executable program; it is where the program control starts and ends.
+- `Main` is declared inside a class or struct. `Main` must be [static](../../../csharp/language-reference/keywords/static.md) and it need not be [public](../../../csharp/language-reference/keywords/public.md). (In the earlier example, it receives the default access of [private](../../../csharp/language-reference/keywords/private.md).) The enclosing class or struct is not required to be static.
+- `Main` can either have a `void`, `int`, or, starting with C# 7.1, `Task`, or `Task<int>` return type.
+- If and only if `Main` returns a `Task` or `Task<int>`, the declaration of `Main` may include the [`async`](../../language-reference/keywords/async.md) modifier. Note that this specifically excludes an `async void Main` method.
+- The `Main` method can be declared with or without a `string[]` parameter that contains command-line arguments. When using [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] to create Windows applications, you can add the parameter manually or else use the <xref:System.Environment> class to obtain the command-line arguments. Parameters are read as zero-indexed command-line arguments. Unlike C and C++, the name of the program is not treated as the first command-line argument.
+
+The addition of `async` and `Task`, `Task<int>` return types simplifies program code when console applications need to start and `await` asynchronous operations in `Main`.
+
+## C# language specification
+
+[!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)]
+
+## See also
+[Command-line Building With csc.exe](../../../csharp/language-reference/compiler-options/command-line-building-with-csc-exe.md)
+[C# Programming Guide](../../../csharp/programming-guide/index.md)
+[Methods](../../../csharp/programming-guide/classes-and-structs/methods.md)
+[Inside a C# Program](../../../csharp/programming-guide/inside-a-program/index.md)

docs/csharp/programming-guide/main-and-command-args/main-return-values.md

@@ -1,7 +1,7 @@
 ---
 title: "Main() Return Values (C# Programming Guide)"
 
-ms.date: "2015-07-20"
+ms.date: "2017-08-02"
 ms.prod: .net
 
 
@@ -33,58 +33,91 @@ translation.priority.ht:
   - "zh-cn"
   - "zh-tw"
 ---
-# Main() Return Values (C# Programming Guide)
-The `Main` method can return `void`:  
-
- [!code-cs[csProgGuideMain#12](../../../csharp/programming-guide/inside-a-program/codesnippet/CSharp/main-return-values_1.cs)]  
-
- It can also return an `int`:  
-
- [!code-cs[csProgGuideMain#13](../../../csharp/programming-guide/inside-a-program/codesnippet/CSharp/main-return-values_2.cs)]  
-
- If the return value from `Main` is not used, returning `void` allows for slightly simpler code. However, returning an integer enables the program to communicate status information to other programs or scripts that invoke the executable file. The following example shows how the return value from `Main` can be accessed.  
-
-## Example  
- In this example, a batch file is used to run a program and test the return value of the `Main` function. When a program is executed in Windows, any value returned from the `Main` function is stored in an environment variable called `ERRORLEVEL`. A batch file can determine the outcome of execution by inspecting the `ERRORLEVEL` variable. Traditionally, a return value of zero indicates successful execution. The following example is a simple program that returns zero from the `Main` function. The zero indicates that the program ran successfully. Save the program as MainReturnValTest.cs.  
-
- [!code-cs[csProgGuideMain#14](../../../csharp/programming-guide/inside-a-program/codesnippet/CSharp/main-return-values_3.cs)]  
-
-## Example  
- Because this example uses a batch file, it is best to compile the code from a command prompt. Follow the instructions in [How to: Set Environment Variables for the Visual Studio Command Line](../../../csharp/language-reference/compiler-options/how-to-set-environment-variables-for-the-visual-studio-command-line.md) to enable command-line builds, or use the Visual Studio Command Prompt, available from the **Start** menu under **Visual Studio Tools**. From the command prompt, navigate to the folder in which you saved the program. The following command compiles MainReturnValTest.cs and produces the executable file MainReturnValTest.exe.  
-
- `csc MainReturnValTest.cs`  
-
- Next, create a batch file to run MainReturnValTest.exe and to display the result. Paste the following code into a text file and save it as `test.bat` in the folder that contains MainReturnValTest.cs and MainReturnValTest.exe. Run the batch file by typing `test` at the command prompt.  
-
- Because the code returns zero, the batch file will report success. However, if you change MainReturnValTest.cs to return a non-zero value and then re-compile the program, subsequent execution of the batch file will report failure.  
-
-```  
-rem test.bat  
-@echo off  
-MainReturnValTest  
-@if "%ERRORLEVEL%" == "0" goto good  
-
-:fail  
-    echo Execution Failed  
-    echo return value = %ERRORLEVEL%  
-    goto end  
-
-:good  
-    echo Execution succeeded  
-    echo Return value = %ERRORLEVEL%  
-    goto end  
-
-:end  
-```  
-
-## Sample Output  
- `Execution succeeded`  
-
- `Return value = 0`  
-
-## See Also  
- [C# Programming Guide](../../../csharp/programming-guide/index.md)   
- [C# Reference](../../../csharp/language-reference/index.md)   
- [Main() and Command-Line Arguments](../../../csharp/programming-guide/main-and-command-args/index.md)   
- [How to: Display Command Line Arguments](../../../csharp/programming-guide/main-and-command-args/how-to-display-command-line-arguments.md)   
- [How to: Access Command-Line Arguments Using foreach](../../../csharp/programming-guide/main-and-command-args/how-to-access-command-line-arguments-using-foreach.md)
+
+# Main() return values (C# Programming Guide)
+
+The `Main` method can return `void`:
+
+[!code-cs[csProgGuideMain#12](../../../csharp/programming-guide/inside-a-program/codesnippet/CSharp/main-return-values_1.cs)]
+
+It can also return an `int`:
+
+[!code-cs[csProgGuideMain#13](../../../csharp/programming-guide/inside-a-program/codesnippet/CSharp/main-return-values_2.cs)]
+
+If the return value from `Main` is not used, returning `void` allows for slightly simpler code. However, returning an integer enables the program to communicate status information to other programs or scripts that invoke the executable file. The return value from `Main` is treated as the exit code for the process. The following example shows how the return value from `Main` can be accessed.
+
+## Example
+
+This example uses [.NET Core](../../../core/index.md) command line tools. If you are unfamilar with .NET Core command line tools, you can learn about them in this [Get started topic](../../../core/tutorials/using-with-xplat-cli.md).
+
+Modify the `Main` method in *program.cs* as follows:
+
+[!code-cs[csProgGuideMain#14](../../../csharp/programming-guide/inside-a-program/codesnippet/CSharp/main-return-values_3.cs)]
+
+When a program is executed in Windows, any value returned from the `Main` function is stored in an environment variable. This environment variable can be retrieved using `ERRORLEVEL` from a batch file, or `$LastExitCode` from powershell.
+
+You can build the application using the [dotnet CLI](../../../core/tools/dotnet.md) `dotnet build` command.
+
+Next, create a Powershell script to run the application and display the result. Paste the following code into a text file and save it as `test.ps1` in the folder that contains the project. Run the powershell script by typing `test.ps1` at the powershell prompt.
+
+Because the code returns zero, the batch file will report success. However, if you change MainReturnValTest.cs to return a non-zero value and then re-compile the program, subsequent execution of the powershell script will report failure.
+
+```powershell
+dotnet run
+if ($LastExitCode -eq 0) {
+    Write-Host "Execution succeeded"
+} else
+{
+    Write-Host "Execution Failed"
+}
+Write-Host "Return value = " $LastExitCode
+```
+
+## Sample output
+
+```txt
+Execution succeeded
+Return value = 0
+```
+
+## Async Main return values
+
+Async Main return values move the boilerplate code necessary for calling asynchronous methods in `Main` to code generated by the compiler. Previously, you would need to write this construct to call asynchronous code and ensure your program ran until the asynchronous operation completed:
+
+```csharp
+public static void Main()
+{
+    AsyncConsoleWork().GetAwaiter().GetResult();
+}
+
+private static async Task<int> AsyncConsoleWork()
+{
+    // Main body here
+    return 0;
+}
+```
+
+Now, this can be replaced by:
+
+[!code-csharp[AsyncMain](../../../../samples/snippets/csharp/main-arguments/program.cs#AsyncMain)]
+
+The advantage of the new syntax is that the compiler always generates the correct code.
+
+## Compiler generated code
+
+When the application entry point returns a `Task` or `Task<int>`, the compiler generates a new entry point that calls the entry point method declared in the application code. Assuming that this entry point is called `$GeneratedMain`, the compiler generates the following code for these entry points:
+
+- `static Task Main()` results in the compiler emitting the equivalent of `private static void $GeneratedMain() => Main().GetAwaiter().GetResult();`
+- `static Task Main(string[])` results in the compiler emitting the equivalent of `private static void $GeneratedMain(string[] args) => Main(args).GetAwaiter().GetResult();`
+- `static Task<int> Main()` results in the compiler emitting the equivalent of `private static int $GeneratedMain() => Main().GetAwaiter().GetResult();`
+- `static Task<int> Main(string[])` results in the compiler emitting the equivalent of `private static int $GeneratedMain(string[] args) => Main(args).GetAwaiter().GetResult();`
+
+> [!NOTE]
+>If the examples used `async` modifier on the `Main` method, the compiler would generate the same code.
+
+## See also
+[C# Programming Guide](../../programming-guide/index.md)
+[C# Reference](../index.md)
+[Main() and Command-Line Arguments](index.md)
+[How to: Display Command Line Arguments](../../programming-guide/main-and-command-args/how-to-display-command-line-arguments.md)
+[How to: Access Command-Line Arguments Using foreach](../../programming-guide/main-and-command-args/how-to-access-command-line-arguments-using-foreach.md)

samples/snippets/csharp/main-arguments/Program.cs

@@ -0,0 +1,22 @@
+using System;
+using System.Threading.Tasks;
+
+namespace main_arguments
+{
+    class Program
+    {
+        #region AsyncMain
+        static async Task<int> Main(string[] args)
+        {
+            return await AsyncConsoleWork();
+        }
+        #endregion
+
+        private static async Task<int> AsyncConsoleWork()
+        {
+            await Task.Delay(1000);
+            return 0;
+        }
+
+    }
+}

samples/snippets/csharp/main-arguments/main-arguments.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp2.0</TargetFramework>
+    <LangVersion>latest</LangVersion>
+  </PropertyGroup>
+
+</Project>