async（C# 參考） · MSDN C# 編程指南 & 參考手冊 2015

# async（C# 參考）使用 **async** 修飾符可將方法、[lambda 表達式](https://msdn.microsoft.com/zh-CN/library/bb397687.aspx)或[匿名方法](https://msdn.microsoft.com/zh-CN/library/0yw3tz5k.aspx)指定為異步。如果對方法或表達式使用此修飾符，則其稱為異步方法。 ``` public async Task<int> ExampleMethodAsync() { // . . . . } ``` 如果你不熟悉異步編程或不了解異步方法如何使用 **await** 關鍵字來完成可能需要長時間運行的工作而不阻止調用方的線程，則應閱讀[使用 Async 和 Await 的異步編程（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-CN/library/hh191443.aspx)中的簡介。 ``` string contents = await contentsTask; ``` 方法將同步運行，直至到達其第一個 **await** 表達式，此時會將方法掛起，直到等待的任務完成。同時，如下節示例中所示，控件將返回到方法的調用方。如果 **async** 關鍵字修改的方法不包含 **await** 表達式或語句，則該方法將同步執行。編譯器警告將通知你不包含 **await** 的任何異步方法，因為該情況可能表示存在錯誤。請參見[編譯器警告（等級 1）CS4014](https://msdn.microsoft.com/zh-CN/library/hh873131.aspx)。 **async** 關鍵字是上下文關鍵字，原因在于只有當它修飾方法、lambda 表達式或匿名方法時，它才是關鍵字。在所有其他上下文中，都會將其解釋為標識符。 ## 示例下面的示例展示了異步事件處理程序 StartButton_Click 和異步方法 ExampleMethodAsync 之間的控制結構和流程。此異步方法得到的結果是一個下載網站的長度。此代碼適用于在 Visual Studio 2013 中創建的 Windows Presentation Foundation (WPF) 應用或 Windows 應用商店應用；請參見有關設置應用的代碼注釋。 ``` // You can run this code in Visual Studio 2013 as a WPF app or a Windows Store app. // You need a button (StartButton) and a textbox (ResultsTextBox). // Remember to set the names and handler so that you have something like this: // <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="TextBox" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/> // To run the code as a WPF app: // paste this code into the MainWindow class in MainWindow.xaml.cs, // add a reference to System.Net.Http, and // add a using directive for System.Net.Http. // To run the code as a Windows Store app: // paste this code into the MainPage class in MainPage.xaml.cs, and // add using directives for System.Net.Http and System.Threading.Tasks. 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}\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; } // Output: // Preparing to finish ExampleMethodAsync. // Length: 53292 ``` | ![System_CAPS_important](https://box.kancloud.cn/2016-01-31_56adb62ec9ef4.jpeg)重要事項 | | :-- | | 有關各項任務以及在等待任務期間所執行代碼的更多信息，請參見[使用 Async 和 Await 的異步編程（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-CN/library/hh191443.aspx)。有關使用類似元素的完整 WPF 示例，請參見[演練：使用 Async 和 Await 訪問 Web（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-CN/library/hh300224.aspx)。你可以從[開發人員代碼示例](http://go.microsoft.com/fwlink/?LinkId=255191)下載演練代碼。 | ## 返回類型異步方法的返回類型可以為 [Task](https://msdn.microsoft.com/zh-CN/library/system.threading.tasks.task.aspx)、[Task<TResult>](https://msdn.microsoft.com/zh-CN/library/dd321424.aspx) 或 [void](https://msdn.microsoft.com/zh-CN/library/yah0tteb.aspx)。方法不能聲明任何 [ref](https://msdn.microsoft.com/zh-CN/library/14akc2c7.aspx) 或 [out](https://msdn.microsoft.com/zh-CN/library/t3c3bfhx.aspx) 參數，但是可以調用具有這類參數的方法。如果異步方法的[返回](https://msdn.microsoft.com/zh-CN/library/1h3swy84.aspx)語句指定一個 **TResult** 類型的操作數，則你應指定 **Task<TResult>** 作為方法的返回類型。如果當方法完成時未返回有意義的值，則應使用 **Task**。即，對方法的調用將返回一個 **Task**，但是當 **Task** 完成時，任何等待 **Task** 的所有 **await** 表達式的計算結果都為 **void**。你應主要使用 **void** 返回類型來定義事件處理程序，這些處理程序需要此返回類型。 **void** 返回異步方法的調用方不能等待，并且無法捕獲該方法引發的異常。有關更多信息和示例，請參見[異步返回類型（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-CN/library/hh524395.aspx)。 ## 請參閱 [AsyncStateMachineAttribute](https://msdn.microsoft.com/zh-CN/library/system.runtime.compilerservices.asyncstatemachineattribute.aspx) [await（C# 參考）](https://msdn.microsoft.com/zh-CN/library/hh156528.aspx) [演練：使用 Async 和 Await 訪問 Web（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-CN/library/hh300224.aspx) [使用 Async 和 Await 的異步編程（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-CN/library/hh191443.aspx)