await-operatorn – väntar asynkront på att en uppgift ska slutföras

  • Artikel

Operatorn await pausar utvärderingen av den omslutande asynkrona metoden tills den asynkrona åtgärd som representeras av dess operand har slutförts. När den asynkrona åtgärden är klar returnerar operatorn await resultatet av åtgärden, om någon. När operatorn await tillämpas på operanden som representerar en redan slutförd åtgärd returnerar den resultatet av åtgärden omedelbart utan att omslutningsmetoden avbryts. Operatorn await blockerar inte tråden som utvärderar asynkron metod. När operatorn await pausar den omslutande asynkrona metoden återgår kontrollen till metodens anropare.

I följande exempel HttpClient.GetByteArrayAsync returnerar metoden instansen Task<byte[]> , som representerar en asynkron åtgärd som genererar en bytematris när den är klar. Tills åtgärden har slutförts pausar operatorn awaitDownloadDocsMainPageAsync metoden. När DownloadDocsMainPageAsync pausas returneras kontrollen till Main metoden, som är anroparen för DownloadDocsMainPageAsync. Metoden Main körs tills den behöver resultatet av den asynkrona åtgärd som utförs av DownloadDocsMainPageAsync metoden. När GetByteArrayAsync hämtar alla byte utvärderas resten av DownloadDocsMainPageAsync metoden. Därefter utvärderas resten av Main metoden.

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.

Operand för ett await uttryck måste ange för meddelande när en uppgift har slutförts. I allmänhet anropas ett ombud när uppgiften slutförs, antingen utan framgång eller utan framgång. Avsnittet await i C#-språkspecifikationen innehåller information om hur dessa meddelanden implementeras.

I föregående exempel används metoden asyncMain. Mer information finns i operatorn await i avsnittet Main-metod .

Kommentar

En introduktion till asynkron programmering finns i Asynkron programmering med asynkron asynkron programmering och väntar. Asynkron programmering med async och await följer det aktivitetsbaserade asynkrona mönstret.

Du kan bara använda operatorn await i en metod, lambda-uttryck eller anonym metod som ändras av nyckelordet async . Inom en asynkron metod kan du inte använda operatorn await i en synkron funktions brödtext, i blocket för en låssats och i en osäker kontext.

Operatorns await operande är vanligtvis av någon av följande .NET-typer: Task, Task<TResult>, ValueTaskeller ValueTask<TResult>. Alla väntande uttryck kan dock vara operatorns await operand. Mer information finns i avsnittet Awaitable expressions (Väntande uttryck) i C#-språkspecifikationen.

Typen av uttryck await t är TResult om typen av uttryck t är Task<TResult> eller ValueTask<TResult>. Om typen av t är Task eller ValueTask, är voidtypen av await t . I båda fallen, om t genererar ett undantag, await t återväxar undantaget.

Asynkrona strömmar och engångsströmmar

Du använder -instruktionen await foreach för att använda en asynkron dataström. Mer information finns i instruktionsavsnittet foreach i artikeln Iteration-instruktioner.

Du använder -instruktionen await using för att arbeta med ett asynkront disponibelt objekt, dvs. ett objekt av en typ som implementerar ett IAsyncDisposable gränssnitt. Mer information finns i avsnittet Använda asynkron disponibel i artikeln Implementera en DisposeAsync-metod.

await-operatorn i Main-metoden

MetodenMain, som är programmets startpunkt, kan returnera Task eller Task<int>, vilket gör att den är asynkron så att du kan använda operatorn await i dess brödtext. För att säkerställa att metoden väntar på att Main en asynkron åtgärd ska slutföras i tidigare C#-versioner kan du hämta värdet för egenskapen för den Task<TResult>.ResultTask<TResult> instans som returneras av motsvarande asynkron metod. För asynkrona åtgärder som inte genererar ett värde kan du anropa Task.Wait metoden. Information om hur du väljer språkversion finns i C#-språkversioner.

Språkspecifikation för C#

Mer information finns i avsnittet Await expressions (Vänta-uttryck) i språkspecifikationen C#.

Se även