async（C# 参考）

使用 async 修饰符可将方法、lambda 表达式或匿名方法指定为异步。 如果对方法或表达式使用此修饰符，则其称为异步方法 。 如下示例定义了一个名为 ExampleMethodAsync 的异步方法：

public async Task<int> ExampleMethodAsync()
{
    //...
}

如果不熟悉异步编程，或者不了解异步方法如何在不阻止调用方线程的情况下使用 await 运算符执行可能需要长时间运行的工作，请参阅使用 Async 和 Await 的异步编程中的说明。 如下代码见于一种异步方法中，且调用 HttpClient.GetStringAsync 方法：

string contents = await httpClient.GetStringAsync(requestUrl);

异步方法同步运行，直至到达其第一个 await 表达式，此时会将方法挂起，直到等待的任务完成。 同时，如下节示例中所示，控件将返回到方法的调用方。

如果 async 关键字修改的方法不包含 await 表达式或语句，则该方法将同步执行。 编译器警告将通知你不包含 await 语句的任何异步方法，因为该情况可能表示存在错误。 请参阅编译器警告（等级 1）CS4014。

async 关键字是上下文关键字，原因在于只有当它修饰方法、lambda 表达式或匿名方法时，它才是关键字。 在所有其他上下文中，都会将其解释为标识符。

示例

下面的示例展示了异步事件处理程序 StartButton_Click 和异步方法 ExampleMethodAsync 之间的控制结构和流程。 此异步方法的结果是 Web 页面的字符数。 此代码适用于在 Visual Studio 中创建的 Windows Presentation Foundation (WPF) 应用或 Windows 应用商店应用；请参见有关设置应用的代码注释。

可以在 Visual Studio 中将此代码作为 Windows Presentation Foundation (WPF) 应用或 Windows 应用商店应用运行。 需要一个名为 StartButton 的按钮控件和一个名为 ResultsTextBox 的文本框控件。 切勿忘记设置名称和处理程序，以便获得类似于以下代码的内容：

<Button Content="Button" HorizontalAlignment="Left" Margin="88,77,0,0" VerticalAlignment="Top" Width="75"
        Click="StartButton_Click" Name="StartButton"/>
<TextBox HorizontalAlignment="Left" Height="137" Margin="88,140,0,0" TextWrapping="Wrap"
         Text="&lt;Enter a URL&gt;" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/>

将代码作为 WPF 应用运行：

• 将此代码粘贴到 MainWindow.xaml.cs 中的 MainWindow 类中。
• 添加对 System.Net.Http 的引用。
• 为 System.Net.Http 添加一个 using 指令。

将此代码作为 Windows 应用商店应用运行：

• 将此代码粘贴到 MainPage.xaml.cs 中的 MainPage 类中。
• 为 System.Net.Http 和 System.Threading.Tasks 添加 using 指令。

private async void StartButton_Click(object sender, RoutedEventArgs e)
{
    // ExampleMethodAsync returns a Task<int>, which means that the method
    // eventually produces an int result. However, ExampleMethodAsync returns
    // the Task<int> value as soon as it reaches an await.
    ResultsTextBox.Text += "\n";

    try
    {
        int length = await ExampleMethodAsync();
        // Note that you could put "await ExampleMethodAsync()" in the next line where
        // "length" is, but due to when '+=' fetches the value of ResultsTextBox, you
        // would not see the global side effect of ExampleMethodAsync setting the text.
        ResultsTextBox.Text += String.Format("Length: {0:N0}\n", length);
    }
    catch (Exception)
    {
        // Process the exception if one occurs.
    }
}

public async Task<int> ExampleMethodAsync()
{
    var httpClient = new HttpClient();
    int exampleInt = (await httpClient.GetStringAsync("http://msdn.microsoft.com")).Length;
    ResultsTextBox.Text += "Preparing to finish ExampleMethodAsync.\n";
    // After the following return statement, any method that's awaiting
    // ExampleMethodAsync (in this case, StartButton_Click) can get the
    // integer result.
    return exampleInt;
}
// The example displays the following output:
// Preparing to finish ExampleMethodAsync.
// Length: 53292

返回类型

异步方法可具有以下返回类型：

• Task
• Task<TResult>
• void。 对于除事件处理程序以外的代码，通常不鼓励使用 async void 方法，因为调用方不能 await 那些方法，并且必须实现不同的机制来报告成功完成或错误条件。
• 任何具有可访问的 GetAwaiter 方法的类型。 System.Threading.Tasks.ValueTask<TResult> 类型属于此类实现。 它通过添加 NuGet 包 System.Threading.Tasks.Extensions 的方式可用。

此异步方法既不能声明任何 in、ref 或 out 参数，也不能具有引用返回值，但它可以调用具有此类参数的方法。

如果异步方法的 语句指定一个 类型的操作数，则应指定 Task<TResult> 作为方法的返回类型TResult。 如果当方法完成时未返回有意义的值，则应使用 Task。 即，对方法的调用将返回一个 Task，但是当 Task 完成时，任何等待 await 的所有 Task 表达式的计算结果都为 void。

你应主要使用 void 返回类型来定义事件处理程序，这些处理程序需要此返回类型。 void 返回异步方法的调用方不能等待，并且无法捕获该方法引发的异常。

返回另一个类型（通常为值类型），该类型具有 GetAwaiter 方法，可最大程度减少代码段性能关键中的内存分配。

有关详细信息和示例，请参阅异步返回类型。

请参阅

• AsyncStateMachineAttribute
• await
• 使用 Async 和 Await 的异步编程
• 在异步任务完成时对其进行处理