Async (Visual Basic)
Updated: July 20, 2015
For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
Async modifier indicates that the method or lambda expression that it modifies is asynchronous. Such methods are referred to as async methods.
An async method provides a convenient way to do potentially long-running work without blocking the caller's thread. The caller of an async method can resume its work without waiting for the async method to finish.
The following example shows the structure of an async method. By convention, async method names end in "Async."
Public Async Function ExampleMethodAsync() As Task(Of Integer) ' . . . ' At the Await expression, execution in this method is suspended and, ' if AwaitedProcessAsync has not already finished, control returns ' to the caller of ExampleMethodAsync. When the awaited task is ' completed, this method resumes execution. Dim exampleInt As Integer = Await AwaitedProcessAsync() ' . . . ' The return statement completes the task. Any method that is ' awaiting ExampleMethodAsync can now get the integer result. Return exampleInt End Function
Typically, a method modified by the
Async keyword contains at least one Await expression or statement. The method runs synchronously until it reaches the first
Await, at which point it suspends until the awaited task completes. In the meantime, control is returned to the caller of the method. If the method doesn’t contain an
Await expression or statement, the method isn’t suspended and executes as a synchronous method does. A compiler warning alerts you to any async methods that don't contain
Await because that situation might indicate an error. For more information, see the compiler error.
Async keyword is an unreserved keyword. It is a keyword when it modifies a method or a lambda expression. In all other contexts, it is interpreted as an identifier.
Task(Of TResult) for the return type of an async method if the Return statement of the method has an operand of type TResult. You use
Task if no meaningful value is returned when the method is completed. That is, a call to the method returns a
Task, but when the
Task is completed, any
Await statement that's awaiting the
Task doesn’t produce a result value.
Async subroutines are used primarily to define event handlers where a
Sub procedure is required. The caller of an async subroutine can't await it and can't catch exceptions that the method throws.
For more information and examples, see Async Return Types.
The following examples show an async event handler, an async lambda expression, and an async method. For a full example that uses these elements, see Walkthrough: Accessing the Web by Using Async and Await. You can download the walkthrough code from Developer Code Samples.
' An event handler must be a Sub procedure. Async Sub button1_Click(sender As Object, e As RoutedEventArgs) Handles button1.Click textBox1.Clear() ' SumPageSizesAsync is a method that returns a Task. Await SumPageSizesAsync() textBox1.Text = vbCrLf & "Control returned to button1_Click." End Sub ' The following async lambda expression creates an equivalent anonymous ' event handler. AddHandler button1.Click, Async Sub(sender, e) textBox1.Clear() ' SumPageSizesAsync is a method that returns a Task. Await SumPageSizesAsync() textBox1.Text = vbCrLf & "Control returned to button1_Click." End Sub ' The following async method returns a Task(Of T). ' A typical call awaits the Byte array result: ' Dim result As Byte() = Await GetURLContents("http://msdn.com") Private Async Function GetURLContentsAsync(url As String) As Task(Of Byte()) ' The downloaded resource ends up in the variable named content. Dim content = New MemoryStream() ' Initialize an HttpWebRequest for the current URL. Dim webReq = CType(WebRequest.Create(url), HttpWebRequest) ' Send the request to the Internet resource and wait for ' the response. Using response As WebResponse = Await webReq.GetResponseAsync() ' Get the data stream that is associated with the specified URL. Using responseStream As Stream = response.GetResponseStream() ' Read the bytes in responseStream and copy them to content. ' CopyToAsync returns a Task, not a Task<T>. Await responseStream.CopyToAsync(content) End Using End Using ' Return the result as a byte array. Return content.ToArray() End Function