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

# await（C# 參考） **await** 運算符在異步方法應用于任務，以掛起執行方法，直到所等待的任務完成。任務表示正在進行的工作。在其中使用 **await** 的異步方法必須通過 [async](https://msdn.microsoft.com/zh-cn/library/hh156513.aspx) 關鍵字進行修改。使用 **async** 修飾符定義并且通常包含一個或多個 **await** 表達式的這類方法稱為_異步方法_。 | ![](https://box.kancloud.cn/2016-01-31_56adb62c1380a.jpg) 注意 | | :-- | | **async** 和 **await** 關鍵字是在 Visual Studio 2012 中引入的。有關異步編程的說明，請參閱[使用 Async 和 Await 的異步編程（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-cn/library/hh191443.aspx)。 | 應用 **await** 運算符的任務通常是實現[基于任務的異步模式](http://go.microsoft.com/fwlink/?LinkId=204847)的方法調用的返回值。示例包括 [Task](https://msdn.microsoft.com/zh-cn/library/system.threading.tasks.task.aspx) 或 [Task<TResult>](https://msdn.microsoft.com/zh-cn/library/dd321424.aspx) 類型的值。在以下代碼中，[HttpClient](https://msdn.microsoft.com/zh-cn/library/system.net.http.httpclient.aspx) 方法 [GetByteArrayAsync](https://msdn.microsoft.com/zh-cn/library/hh551751.aspx) 返回 **Task<byte[]>** (getContentsTask)。當任務完成時，任務約定生成實際字節數組。 **await** 運算符應用于 getContentsTask 以在 SumPageSizesAsync 中掛起執行，直到 getContentsTask 完成。同時，控制權會返回給 SumPageSizesAsync 的調用方。當 getContentsTask 完成之后，**await** 表達式計算為字節數組。 ``` private async Task SumPageSizesAsync() { // To use the HttpClient type in desktop apps, you must include a using directive and add a // reference for the System.Net.Http namespace. HttpClient client = new HttpClient(); // . . . Task<byte[]> getContentsTask = client.GetByteArrayAsync(url); byte[] urlContents = await getContentsTask; // Equivalently, now that you see how it works, you can write the same thing in a single line. //byte[] urlContents = await client.GetByteArrayAsync(url); // . . . } ``` | ![System_CAPS_important](https://box.kancloud.cn/2016-01-31_56adb62ec9ef4.jpeg)重要事項 | | :-- | | 有關完整示例，請參閱[演練：使用 Async 和 Await 訪問 Web（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-cn/library/hh300224.aspx)。可以從 Microsoft 網站上的[開發人員代碼示例](http://go.microsoft.com/fwlink/?LinkID=255191&clcid=0x409)下載該示例。該示例處于 AsyncWalkthrough_HttpClient 項目中。 | 如前面的示例中所示，如果 **await** 應用于返回 **Task<TResult>** 的方法調用結果，則 **await** 表達式的類型為 TResult。如果 **await** 應用于返回 **Task** 的方法調用結果，則 **await** 表達式的類型為 void。以下示例演示了差異。 ``` // Keyword await used with a method that returns a Task<TResult>. TResult result = await AsyncMethodThatReturnsTaskTResult(); // Keyword await used with a method that returns a Task. await AsyncMethodThatReturnsTask(); ``` **await** 表達式不阻止正在執行它的線程。而是使編譯器將剩下的異步方法注冊為等待任務的延續任務。控制權隨后會返回給異步方法的調用方。任務完成時，它會調用其延續任務，異步方法的執行會在暫停的位置處恢復。 **await** 表達式只能在由 **async** 修飾符標記的立即封閉方法體、lambda 表達式或異步方法中出現。術語_“await”_在該上下文中僅用作關鍵字。在其他位置，它會解釋為標識符。在方法、lambda 表達式或匿名方法中，**await** 表達式不能在同步函數體、查詢表達式、[lock 語句](https://msdn.microsoft.com/zh-cn/library/c5kehkcz.aspx)塊或[不安全](https://msdn.microsoft.com/zh-cn/library/chfa2zb8.aspx)上下文中出現。 ## 異常大多數異步方法返回 [Task](https://msdn.microsoft.com/zh-cn/library/system.threading.tasks.task.aspx) 或 [Task<TResult>](https://msdn.microsoft.com/zh-cn/library/dd321424.aspx)。返回任務的屬性攜帶有關其狀態和歷史記錄的信息，如任務是否完成、異步方法是否導致異常或已取消以及最終結果是什么。 **await** 運算符可訪問這些屬性。如果等待的任務返回異步方法導致異常，則 **await** 運算符會重新引發異常。如果等待的任務返回異步方法取消，則 **await** 運算符會重新引發 [OperationCanceledException](https://msdn.microsoft.com/zh-cn/library/system.operationcanceledexception.aspx)。處于故障狀態的單個任務可以反映多個異常。例如，任務可能是對 [Task.WhenAll](https://msdn.microsoft.com/zh-cn/library/hh160374.aspx) 調用的結果。等待此類任務時，等待操作僅重新引發異常之一。但是，無法預測重新引發的異常。有關異步方法中的錯誤處理的示例，請參閱 [try-catch（C# 參考）](https://msdn.microsoft.com/zh-cn/library/0yd65esw.aspx)。下面的 Windows 窗體示例闡釋如何在異步方法 WaitAsynchronouslyAsync 中使用 **await**。將該方法的行為與 WaitSynchronously 的行為進行對比。如果未向任務應用 **await** 運算符，WaitSynchronously 就會同步運行，而不管其定義中是否使用了 **async** 修飾符和在主體中是否調用了 [Thread.Sleep](https://msdn.microsoft.com/zh-cn/library/d00bd51t.aspx)。 ``` private async void button1_Click(object sender, EventArgs e) { // Call the method that runs asynchronously. string result = await WaitAsynchronouslyAsync(); // Call the method that runs synchronously. //string result = await WaitSynchronously (); // Display the result. textBox1.Text += result; } // The following method runs asynchronously. The UI thread is not // blocked during the delay. You can move or resize the Form1 window // while Task.Delay is running. public async Task<string> WaitAsynchronouslyAsync() { await Task.Delay(10000); return "Finished"; } // The following method runs synchronously, despite the use of async. // You cannot move or resize the Form1 window while Thread.Sleep // is running because the UI thread is blocked. public async Task<string> WaitSynchronously() { // Add a using directive for System.Threading. Thread.Sleep(10000); return "Finished"; } ``` ## 請參閱 [使用 Async 和 Await 的異步編程（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-cn/library/hh191443.aspx) [演練：使用 Async 和 Await 訪問 Web（C# 和 Visual Basic）](https://msdn.microsoft.com/zh-cn/library/hh300224.aspx) [async（C# 參考）](https://msdn.microsoft.com/zh-cn/library/hh156513.aspx)