await (Referencia de C#)

Artículo
03/12/2013

Se aplican al operador de await a una tarea en un método asincrónico de suspender la ejecución del método hasta que la tarea aguardada complete.La tarea representa el trabajo en curso.

El método asincrónico en el que se utiliza await debe modificarse mediante la palabra clave de async.Este método, definido mediante el modificador de async, y suele contener una o más expresiones de await, se denomina método async.

[!NOTA]

Las palabras clave de async y de await se introdujeron en Visual Studio 2012.Para obtener información sobre las nuevas características de esa versión, vea Novedades de Visual Studio 2012.

Para obtener una introducción a la programación async, vea Programación asincrónica con Async y Await (C# y Visual Basic).

La tarea a la que se aplican al operador de await normalmente es el valor devuelto por una llamada a un método que implemente Modelo asincrónico basado Tarea-.Incluir valores de ejemplos Task cualquiera de Task<TResult>.

En el código siguiente, el método GetByteArrayAsync de HttpClient devuelve Task<byte[]>, getContentsTask.La tarea es una sugerencia para generar la matriz de bytes real cuando finaliza la tarea.Se aplican al operador de await a getContentsTask para suspender la ejecución en SumPageSizesAsync hasta que se complete getContentsTask.Mientras tanto, el control se devuelve al llamador de SumPageSizesAsync.Cuando finaliza getContentsTask, la expresión de await se evalúa como una matriz de bytes.

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);
    // . . .
}

Importante
Para obtener el ejemplo completo, vea Walkthrough: Acceso a web usando Async y Await (C# y Visual Basic).Puede descargar el ejemplo Ejemplos de código del desarrollador en el sitio Web de Microsoft.El ejemplo está en el proyecto de AsyncWalkthrough_HttpClient.

Como se muestra en el ejemplo anterior, si await se aplica al resultado de una llamada al método que devuelve Task<TResult>, el tipo de expresión de await es TResult.Si await se aplica al resultado de una llamada al método que devuelve Task, el tipo de expresión de await está vacío.El ejemplo siguiente muestra la diferencia.

// 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();

Una expresión de await no bloquea el subproceso en el que se ejecuta.En su lugar, el compilador hace para inscribirse el resto del método async como una continuación en la tarea aguardada.El Control se devuelve al llamador del método async.Cuando la tarea se completa, invoca su continuación, y la ejecución del método async reanuda donde se quedó.

Una expresión de await sólo puede aparecer en el cuerpo de un método inmediatamente envolvente, una expresión lambda, o de método anónimo que está marcado por un modificador de async.El término espera actúa como palabra clave solo en ese contexto.En otra parte, se interpreta como un identificador.Dentro del método, la expresión lambda, o método anónimo, una expresión de await no puede aparecer en el cuerpo de una función sincrónica, en una expresión de consulta, en el bloque de catch o de finally de excepción que administra la instrucción, en el bloque de instrucción lock, o en un contexto de seguro.

Excepciones

La mayoría de los métodos async devuelven Task o Task<TResult>.Las propiedades de la tarea devuelta contienen información sobre su estado e historial, por ejemplo si la tarea se ha completado, si el método async produjo una excepción o se cancela, y cuáles el resultado final es.El operador de await tiene acceso a esas propiedades.

Si se espera un método async tarea- que cambia que produce una excepción, los vuelve de operador de await la excepción.

Si se espera un método async tarea- que cambia que se cancele, los vuelve de operador de awaitOperationCanceledException.

Una única tarea que se con errores puede reflejar varias excepciones.Por ejemplo, la tarea puede ser el resultado de una llamada a Task.WhenAll.Cuando se espera por tarea, los vuelve sólo uno de la operación de aguardar de excepciones.Sin embargo, no puede predecir cuáles de las excepciones son reiniciarse.

Para obtener ejemplos de control de errores en métodos async, vea try-catch (Referencia de C#).

Ejemplo

El ejemplo siguiente de formularios Windows Forms muestra el uso de await en un método async, WaitAsynchronouslyAsync.Compare el comportamiento de ese método con el comportamiento de WaitSynchronously.Sin un operador de await aplicada a una tarea, se ejecuta de WaitSynchronously sincrónicamente a pesar de uso del modificador de async en su definición y una llamada a Thread.Sleep en su cuerpo.

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";
}

Vea también

await (Referencia de C#)

Excepciones

Ejemplo

Vea también

Tareas

Referencia

Conceptos

Recursos adicionales