Share via

async (C#-referens)

  • Artikel

async Använd modifieraren för att ange att en metod, lambda-uttryck eller anonym metod är asynkron. Om du använder den här modifieraren på en metod eller ett uttryck kallas det för en asynkron metod. I följande exempel definieras en asynkron metod med namnet ExampleMethodAsync:

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

Om du är nybörjare på asynkron programmering eller inte förstår hur en asynkron metod använder operatornawaitför att utföra potentiellt tidskrävande arbete utan att blockera anroparens tråd läser du introduktionen i Asynkron programmering med asynkron programmering med asynkron inväntning. Följande kod finns i en asynkron HttpClient.GetStringAsync metod och anropar metoden:

string contents = await httpClient.GetStringAsync(requestUrl);

En asynkron metod körs synkront tills den når sitt första await uttryck, då metoden pausas tills den väntade aktiviteten är klar. Under tiden återgår kontrollen till anroparen för metoden, som exemplet i nästa avsnitt visar.

Om metoden som nyckelordet async ändrar inte innehåller ett uttryck eller en await -instruktion körs metoden synkront. En kompilatorvarning varnar dig om asynkrona metoder som inte innehåller await instruktioner, eftersom den situationen kan tyda på ett fel. Se Kompilatorvarning (nivå 1) CS4014.

Nyckelordet async är kontextuellt eftersom det bara är ett nyckelord när det ändrar en metod, ett lambda-uttryck eller en anonym metod. I alla andra sammanhang tolkas den som en identifierare.

Exempel

I följande exempel visas strukturen och flödet av kontroll mellan en asynkron händelsehanterare, StartButton_Click, och en asynkron metod, ExampleMethodAsync. Resultatet från metoden async är antalet tecken på en webbsida. Koden är lämplig för en WPF-app (Windows Presentation Foundation) eller En Windows Store-app som du skapar i Visual Studio. se kodkommentarna för att konfigurera appen.

Du kan köra den här koden i Visual Studio som en WPF-app (Windows Presentation Foundation) eller en Windows Store-app. Du behöver en knappkontroll med namnet StartButton och en textrutekontroll med namnet ResultsTextBox. Kom ihåg att ange namn och hanterare så att du har något liknande:

<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"/>

Så här kör du koden som en WPF-app:

  • Klistra in den här koden i MainWindow klassen i MainWindow.xaml.cs.
  • Lägg till en referens till System.Net.Http.
  • Lägg till ett using direktiv för System.Net.Http.

Så här kör du koden som en Windows Store-app:

  • Klistra in den här koden i MainPage klassen i MainPage.xaml.cs.
  • Lägg till med hjälp av direktiv för System.Net.Http och 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

Viktigt!

Mer information om uppgifter och koden som körs i väntan på en uppgift finns i Asynkron programmering med asynkron asynkron programmering och väntar. Ett fullständigt konsolexempel som använder liknande element finns i Bearbeta asynkrona uppgifter när de slutförs (C#).

Returtyper

En asynkron metod kan ha följande returtyper:

  • Task
  • Task<TResult>
  • void. async void metoder rekommenderas vanligtvis inte för annan kod än händelsehanterare eftersom anropare inte kan await dessa metoder och måste implementera en annan mekanism för att rapportera lyckade slutförande- eller felvillkor.
  • Alla typer som har en tillgänglig GetAwaiter metod. Typen System.Threading.Tasks.ValueTask<TResult> är en sådan implementering. Det är tillgängligt genom att lägga till NuGet-paketet System.Threading.Tasks.Extensions.

Metoden async kan inte deklarera några in-, referens- eller utdataparametrar, och den kan inte heller ha ett referensreturvärde, men den kan anropa metoder som har sådana parametrar.

Du anger Task<TResult> som returtyp för en asynkron metod om retursatsen för metoden anger en operand av typen TResult. Du använder Task om inget meningsfullt värde returneras när metoden har slutförts. Det vill säga ett anrop till metoden returnerar en Task, men när Task är klar, alla await uttryck som väntar på Task utvärderas till void.

Du använder void returtypen främst för att definiera händelsehanterare, som kräver den returtypen. Anroparen för en void-returning-asynkron metod kan inte invänta den och kan inte fånga undantag som metoden genererar.

Du returnerar en annan typ, vanligtvis en värdetyp, som har en GetAwaiter metod för att minimera minnesallokeringar i prestandakritiska kodavsnitt.

Mer information och exempel finns i Async Return Types (Async Return Types).

Se även