Comparteix via

async (referencia de C#)

Use el modificador async para especificar que un método, una expresión lambda o un método anónimo es asincrónico. Si usa este modificador en un método o expresión, cree un método asincrónico. En el ejemplo siguiente se define un método asincrónico denominado ExampleMethodAsync:

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

La documentación de referencia del lenguaje C# cubre la versión más reciente publicada del lenguaje C#. También contiene documentación inicial sobre las características de las versiones preliminares públicas de la próxima versión del lenguaje.

La documentación identifica cualquier característica introducida por primera vez en las últimas tres versiones del idioma o en las versiones preliminares públicas actuales.

Sugerencia

Para buscar cuándo se introdujo por primera vez una característica en C#, consulte el artículo sobre el historial de versiones del lenguaje C#.

Si no está familiarizado con la programación asincrónica o no entiende cómo un método asincrónico usa el await operador para realizar un trabajo potencialmente de larga duración sin bloquear el subproceso del autor de la llamada, lea la introducción en Programación asincrónica con async y await. El siguiente código se encuentra dentro de un método asincrónico y llama al método HttpClient.GetStringAsync:

string contents = await httpClient.GetStringAsync(requestUrl);

Un método asincrónico se ejecuta sincrónicamente hasta que alcanza su primera await expresión. En ese momento, el método se suspende hasta que se complete la tarea esperada. Mientras tanto, el control vuelve al llamador del método, como se muestra en el ejemplo de la sección siguiente.

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. 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. Vea Advertencia del compilador (nivel 1) CS4014.

La async palabra clave es contextual. Es una palabra clave solo cuando modifica un método, una expresión lambda o un método anónimo. En todos los demás contextos, el compilador lo interpreta como identificador.

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. El resultado del método asincrónico es el número de caracteres de una página web. El código es adecuado para una aplicación de Windows Presentation Foundation (WPF) o una aplicación de la Tienda Windows que creas en Visual Studio. Consulte los comentarios de código para configurar la aplicación.

Puede ejecutar este código en Visual Studio como una aplicación Windows Presentation Foundation (WPF) o una aplicación de la Tienda Windows. Necesita un control de botón denominado StartButton y un control de cuadro de texto denominado ResultsTextBox. Recuerde establecer los nombres y el controlador de manera que tenga algo similar a esto:

<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:

  • Pegue este código en la clase MainWindow en MainWindow.xaml.cs.
  • Agregue una referencia a System.Net.Http.
  • Agregue una directiva using a System.Net.Http.

Para ejecutar el código como una aplicación de la Tienda Windows:

  • Pegue este código en la clase MainPage en MainPage.xaml.cs.
  • Agregue directivas using para System.Net.Http y 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 obtener más información sobre las tareas y el código que se ejecuta mientras se espera la finalización de una tarea, vea Programación asincrónica con async y await. Para ver un ejemplo completo de la consola que usa elementos similares, consulte el artículo Iniciar varias tareas asincrónicas y procesarlas a medida que se completan (C#).

Tipos de retorno

Un método asincrónico puede tener los siguientes tipos de valor devuelto:

  • Task
  • Task<TResult>
  • void. Por lo general, evite usar async void métodos para código distinto de controladores de eventos, ya que los autores de llamadas no await pueden esos métodos y deben implementar un mecanismo diferente para notificar condiciones de finalización o error correctas.
  • Cualquier tipo que tenga un método GetAwaiter accesible. El tipo System.Threading.Tasks.ValueTask<TResult> es una implementación de ese tipo. Está disponible agregando el paquete System.Threading.Tasks.ExtensionsNuGet .

El método asincrónico no puede declarar ningún inparámetro , ref, ref readonlyo out ni puede tener un valor devuelto de referencia. Sin embargo, puede llamar a métodos que tienen estos parámetros.

Especifique 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. Use Task si el método no devuelve ningún valor significativo cuando se completa. 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. Use el void tipo de valor devuelto principalmente para definir controladores de eventos, que requieren ese tipo de valor devuelto. 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. Devuelve otro tipo, normalmente un tipo de valor, que tiene un GetAwaiter método para minimizar las asignaciones de memoria en secciones críticas para el rendimiento del código.

Para más información y ejemplos, vea Tipos de valor devueltos asincrónicos.

Vea también

  • Last updated on