await-operator : wacht asynchroon totdat een taak is voltooid

  • Artikel

De await operator onderbreekt de evaluatie van de asynchrone methode totdat de asynchrone bewerking die wordt vertegenwoordigd door de operand is voltooid. Wanneer de asynchrone bewerking is voltooid, retourneert de await operator het resultaat van de bewerking, indien van toepassing. Wanneer de await operator wordt toegepast op de operand die een reeds voltooide bewerking vertegenwoordigt, retourneert deze het resultaat van de bewerking onmiddellijk zonder ophanging van de insluitmethode. De await operator blokkeert de thread die de asynchrone methode evalueert niet. Wanneer de await operator de asynchrone methode onderbreekt, keert het besturingselement terug naar de aanroeper van de methode.

In het volgende voorbeeld retourneert de HttpClient.GetByteArrayAsync methode het Task<byte[]> exemplaar, dat een asynchrone bewerking vertegenwoordigt die een bytematrix produceert wanneer deze is voltooid. Totdat de bewerking is voltooid, onderbreekt de await operator de DownloadDocsMainPageAsync methode. Wanneer DownloadDocsMainPageAsync wordt onderbroken, wordt het besturingselement teruggezet naar de Main methode, de aanroeper van DownloadDocsMainPageAsync. De Main methode wordt uitgevoerd totdat het resultaat van de asynchrone bewerking moet worden uitgevoerd door de DownloadDocsMainPageAsync methode. Wanneer GetByteArrayAsync alle bytes worden ontvangen, wordt de rest van de DownloadDocsMainPageAsync methode geëvalueerd. Daarna wordt de rest van de Main methode geëvalueerd.

public class AwaitOperator
{
    public static async Task Main()
    {
        Task<int> downloading = DownloadDocsMainPageAsync();
        Console.WriteLine($"{nameof(Main)}: Launched downloading.");

        int bytesLoaded = await downloading;
        Console.WriteLine($"{nameof(Main)}: Downloaded {bytesLoaded} bytes.");
    }

    private static async Task<int> DownloadDocsMainPageAsync()
    {
        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: About to start downloading.");

        var client = new HttpClient();
        byte[] content = await client.GetByteArrayAsync("https://learn.microsoft.com/en-us/");

        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: Finished downloading.");
        return content.Length;
    }
}
// Output similar to:
// DownloadDocsMainPageAsync: About to start downloading.
// Main: Launched downloading.
// DownloadDocsMainPageAsync: Finished downloading.
// Main: Downloaded 27700 bytes.

De operand van een await expressie moet een melding geven wanneer een taak is voltooid. Over het algemeen wordt een gemachtigde aangeroepen wanneer de taak is voltooid, hetzij geslaagd of mislukt. De await sectie van de C#-taalspecificatie bevat de details over hoe deze meldingen worden geïmplementeerd.

In het voorgaande voorbeeld wordt de asynchrone Main methode gebruikt. Zie de wachtoperator in de sectie Main-methode voor meer informatie.

Notitie

Zie Asynchrone programmering met asynchroon programmeren en wachten voor een inleiding tot asynchrone programmering. Asynchroon programmeren met async en await volgt het asynchrone patroon op basis van taken.

U kunt de await operator alleen gebruiken in een methode, lambda-expressie of anonieme methode die wordt gewijzigd door het asynchrone trefwoord. Binnen een asynchrone methode kunt u de await operator niet gebruiken in de hoofdtekst van een synchrone functie, binnen het blok van een vergrendelingsinstructie en in een onveilige context.

De operand van de await operator is meestal van een van de volgende .NET-typen: Task, Task<TResult>, ValueTaskof ValueTask<TResult>. Elke te wachten expressie kan echter de operand van de await operator zijn. Zie de sectie Awaitable-expressies van de C#-taalspecificatie voor meer informatie.

Het type expressie await t is TResult als het type expressie t is Task<TResult> of ValueTask<TResult>. Als het type is of , is het type await tvoid.ValueTaskTaskt Als er in beide gevallen t een uitzondering wordt gegenereerd, await t wordt de uitzondering opnieuw gegooid.

Asynchrone stromen en wegwerpers

U gebruikt de await foreach instructie om een asynchrone gegevensstroom te gebruiken. Zie de foreach instructiesectie van het artikel Iteratie-instructies voor meer informatie.

U gebruikt de await using instructie om te werken met een asynchroon wegwerpobject, dat wil zeggen een object van een type dat een IAsyncDisposable interface implementeert. Zie de sectie Using async disposable van het artikel Een DisposeAsync-methode implementeren voor meer informatie.

await-operator in de Main-methode

De Main methode, het invoerpunt van de toepassing, kan worden geretourneerd Task of Task<int>, zodat deze asynchroon kan zijn, zodat u de operator in de await hoofdtekst ervan kunt gebruiken. In eerdere C#-versies, om ervoor te zorgen dat de Main methode wacht op het voltooien van een asynchrone bewerking, kunt u de waarde ophalen van de eigenschap van het Task<TResult>.ResultTask<TResult> exemplaar dat wordt geretourneerd door de bijbehorende asynchrone methode. Voor asynchrone bewerkingen die geen waarde produceren, kunt u de Task.Wait methode aanroepen. Zie C#-taalversiebeheer voor informatie over het selecteren van de taalversie.

C#-taalspecificatie

Zie de sectie Await-expressies van de C#-taalspecificatie voor meer informatie.

Zie ook