async (Referencia de C#)async (C# Reference)

Use el modificador async para especificar que un método, una expresión lambda o un método anónimo es asincrónico.Use the async modifier to specify that a method, lambda expression, or anonymous method is asynchronous. Si usa este modificador en un método o una expresión, se hace referencia al mismo como un método asincrónico.If you use this modifier on a method or expression, it's referred to as an async method. En el ejemplo siguiente se define un método asincrónico denominado ExampleMethodAsync:The following example defines an async method named ExampleMethodAsync:

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

Si no está familiarizado con la programación asincrónica o no entiende cómo un método asincrónico usa la palabra clave await para hacer el trabajo de larga duración sin bloquear el subproceso del autor de la llamada, lea la introducción de Programación asincrónica con async y await.If you're new to asynchronous programming or do not understand how an async method uses the await keyword to do potentially long-running work without blocking the caller’s thread, read the introduction in Asynchronous Programming with async and await. El siguiente código se encuentra dentro de un método asincrónico y llama al método HttpClient.GetStringAsync:The following code is found inside an async method and calls the HttpClient.GetStringAsync method:

string contents = await httpClient.GetStringAsync(requestUrl);  

Un método asincrónico se ejecuta sincrónicamente hasta alcanzar la primera expresión await, en la que se suspende el método hasta que se complete la tarea en espera.An async method runs synchronously until it reaches its first await expression, at which point the method is suspended until the awaited task is complete. Mientras tanto, el control vuelve al llamador del método, como se muestra en el ejemplo de la sección siguiente.In the meantime, control returns to the caller of the method, as the example in the next section shows.

Si el método que la palabra clave async modifica no contiene una expresión o instrucción await, el método se ejecuta de forma sincrónica.If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. Una advertencia del compilador alerta de cualquier método asincrónico que no contenga instrucciones de await, porque esa situación podría indicar un error.A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. Vea Compiler Warning (level 1) CS4014 (Advertencia del compilador (nivel 1) CS4014).See Compiler Warning (level 1) CS4014.

La palabra clave async es contextual en el sentido de que es una palabra clave cuando modifica un método, una expresión lambda o un método anónimo.The async keyword is contextual in that it's a keyword only when it modifies a method, a lambda expression, or an anonymous method. En todos los demás contextos, se interpreta como identificador.In all other contexts, it's interpreted as an identifier.

EjemploExample

En el ejemplo siguiente se muestra la estructura y el flujo de control entre un controlador de eventos asincrónicos, StartButton_Click, y un método asincrónico, ExampleMethodAsync.The following example shows the structure and flow of control between an async event handler, StartButton_Click, and an async method, ExampleMethodAsync. El resultado del método asincrónico es el número de caracteres de una página web.The result from the async method is the number of characters of a web page. El código es adecuado para una aplicación Windows Presentation Foundation (WPF) o de la Tienda Windows creada en Visual Studio; vea los comentarios del código para configurar la aplicación.The code is suitable for a Windows Presentation Foundation (WPF) app or Windows Store app that you create in Visual Studio; see the code comments for setting up the app.

Puede ejecutar este código en Visual Studio como una aplicación Windows Presentation Foundation (WPF) o una aplicación de la Tienda Windows.You can run this code in Visual Studio as a Windows Presentation Foundation (WPF) app or a Windows Store app. Necesita un control de botón denominado StartButton y un control de cuadro de texto denominado ResultsTextBox.You need a Button control named StartButton and a Textbox control named ResultsTextBox. Recuerde establecer los nombres y el controlador de manera que tenga algo similar a esto: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="&lt;Enter a URL&gt;" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/>  

Para ejecutar el código como una aplicación WPF:To run the code as a WPF app:

  • Pegue este código en la clase MainWindow en MainWindow.xaml.cs.Paste this code into the MainWindow class in MainWindow.xaml.cs.
  • Agregue una referencia a System.Net.Http.Add a reference to System.Net.Http.
  • Agregue una directiva using a System.Net.Http.Add a using directive for System.Net.Http.

Para ejecutar el código como una aplicación de la Tienda Windows:To run the code as a Windows Store app:

  • Pegue este código en la clase MainPage en MainPage.xaml.cs.Paste this code into the MainPage class in MainPage.xaml.cs.
  • Agregue directivas using para System.Net.Http y System.Threading.Tasks.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: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  

Importante

Para más información sobre las tareas y el código que se ejecuta mientras se espera la finalización por una tarea, vea Programación asincrónica con async y await.For more information about tasks and the code that executes while waiting for a task, see Asynchronous Programming with async and await. Para obtener un ejemplo completo de WPF que usa elementos similares, vea Walkthrough: Accessing the Web by Using Async and Await (Tutorial: obtener acceso a la web con Async y Await).For a full WPF example that uses similar elements, see Walkthrough: Accessing the Web by Using Async and Await.

Tipos de valor devueltosReturn Types

Un método asincrónico puede tener los siguientes tipos de valor devuelto:An async method can have the following return types:

  • Task
  • Task<TResult>
  • void, que solo se debe usar para controladores de eventos.void, which should only be used for event handlers.
  • A partir de C# 7.0, cualquier tipo que tenga un método GetAwaiter accesible.Starting with C# 7.0, any type that has an accessible GetAwaiter method. El tipo System.Threading.Tasks.ValueTask<TResult> es una implementación de ese tipo.The System.Threading.Tasks.ValueTask<TResult> type is one such implementation. Está disponible agregando el paquete NuGet System.Threading.Tasks.Extensions.It is available by adding the NuGet package System.Threading.Tasks.Extensions.

El método asincrónico no puede declarar ningún parámetro in, ref o out, ni puede tener un valor devuelto de referencia, pero puede llamar a los métodos que tienen estos parámetros.The async method can't declare any in, ref or out parameters, nor can it have a reference return value, but it can call methods that have such parameters.

Se puede especificar Task<TResult> como el tipo de valor devuelto de un método asincrónico si la instrucción return del método especifica un operando de tipo TResult.You specify Task<TResult> as the return type of an async method if the return statement of the method specifies an operand of type TResult. Utilice Task si no se devuelve ningún valor significativo al completarse el método.You use Task if no meaningful value is returned when the method is completed. Es decir, una llamada al método devuelve Task, pero cuando se completa Task, las expresiones await que esperan a que Task finalice se evalúan como void.That is, a call to the method returns a Task, but when the Task is completed, any await expression that's awaiting the Task evaluates to void.

El tipo devuelto void se utiliza principalmente para definir controladores de eventos, que requieren ese tipo devuelto.You use the void return type primarily to define event handlers, which require that return type. El llamador de un método asincrónico que devuelva void no puede esperar a que finalice y no puede detectar las excepciones que el método inicia.The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

A partir de C# 7.0, devuelve otro tipo, normalmente un tipo de valor, que tiene un método GetAwaiter para minimizar las asignaciones de memoria en secciones críticas de rendimiento del código.Starting with C# 7.0, you return another type, typically a value type, that has a GetAwaiter method to miminize memory allocations in performance-critical sections of code.

Para más información y ejemplos, vea Tipos de valor devueltos asincrónicos.For more information and examples, see Async Return Types.

Vea tambiénSee Also

AsyncStateMachineAttribute
awaitawait
Tutorial: Acceso a Web mediante Async y AwaitWalkthrough: Accessing the Web by Using Async and Await
Programación asincrónica con Async y AwaitAsynchronous Programming with async and await