Runnable C# Docs: Async Await

Q: How do async and await work in C#?

Marking a method async lets it use await. When the method reaches await on a task that has not finished, it returns to its caller immediately, handing back a Task that represents the rest of the work. When the awaited operation completes, the method resumes after the await. No thread sits blocked while it waits.

Q: What is the difference between Task and Task ?

Task represents an operation that produces no value, the async version of a void method. Task represents one that produces a T: await on a Task gives you the int. An async method declared async Task just writes return 42;, and the compiler wraps it in the task.

Q: How do I run multiple async operations at the same time?

Start them all first, then await them together: var a = GetUserAsync(); var b = GetOrdersAsync(); await Task.WhenAll(a, b);. Writing await GetUserAsync(); await GetOrdersAsync(); runs them one after another, so the total time is the sum instead of the longest one.

Q: Why is async void bad in C#?

An async void method cannot be awaited, so the caller does not know when it finishes, and an exception thrown inside it cannot be caught by the caller: it is raised on the synchronization context and usually crashes the process. Return Task instead. async void exists only for event handlers, whose signature requires void.

Q: Can Main be async in C#?

Yes, since C# 7.1: static async Task Main() or static async Task Main(). Top-level statements (C# 9) can use await directly. In older code, the equivalent is calling MainAsync().GetAwaiter().GetResult() from a normal Main, which is safe there because a console app has no synchronization context.

Most slow operations in a program are waits: for a web server to answer, a database to return rows, a file to be read. async and await let a method pause during such a wait without holding a thread hostage, then continue where it left off. The code still reads top to bottom like ordinary code.

A first async method

An async method returns Task (no result) or Task<T> (a result of type T). Inside it, await waits for another task and gives you its result.

using System;
using System.Threading.Tasks;

class Program
{
    static async Task<decimal> GetPriceAsync(string product)
    {
        await Task.Delay(200);          // stands in for a network call
        return product == "tea" ? 2.50m : 4.00m;
    }

    static async Task RunAsync()
    {
        decimal tea = await GetPriceAsync("tea");
        decimal cake = await GetPriceAsync("cake");
        Console.WriteLine("Tea " + tea + ", cake " + cake + ", total " + (tea + cake));
    }

    static void Main()
    {
        RunAsync().GetAwaiter().GetResult();
    }
}

Output:

Tea 2.50, cake 4.00, total 6.50

GetPriceAsync says return 2.50m, and the compiler wraps that in the Task<decimal> the method returns. await unwraps it again. Task.Delay is the async version of Thread.Sleep: it completes after the time has passed, without blocking a thread in the meantime.

Since C# 7.1, Main itself can be async, and that is how you would write this program in modern .NET:

static async Task Main()
{
    decimal tea = await GetPriceAsync("tea");
    Console.WriteLine(tea);
}

The runnable examples on this page call an async RunAsync method from a regular Main with .GetAwaiter().GetResult(), which is what the compiler generates for an async Main. In a console app that is safe; the deadlock section explains why the same call is dangerous in UI code.

What happens at an await

An async method runs synchronously until its first await on an unfinished task. At that point it returns a Task to its caller, and the rest of the method becomes a continuation that runs when the awaited task completes.

using System;
using System.Threading.Tasks;

class Program
{
    static async Task DownloadAsync()
    {
        Console.WriteLine("  Download: starting");
        await Task.Delay(300);
        Console.WriteLine("  Download: finished");
    }

    static async Task RunAsync()
    {
        Console.WriteLine("Calling DownloadAsync");
        Task download = DownloadAsync();          // runs until its first await
        Console.WriteLine("DownloadAsync returned a task; doing other work");
        await download;                           // now wait for it
        Console.WriteLine("Download awaited");
    }

    static void Main()
    {
        RunAsync().GetAwaiter().GetResult();
    }
}

Output:

Calling DownloadAsync
  Download: starting
DownloadAsync returned a task; doing other work
  Download: finished
Download awaited

"Download: starting" prints before DownloadAsync returns, because everything up to the first await runs on the caller's thread. Then the method hands back an unfinished task, the caller keeps going, and "Download: finished" appears only when the delay is over. Calling an async method starts it; awaiting it is how you wait for the result.

async does not create a thread. While the method is paused there is no thread waiting on it at all, which is why a server can have thousands of requests waiting on a database with only a handful of threads. For CPU-heavy work that should run on another thread, use Task.Run, covered in tasks.

Running operations at the same time with Task.WhenAll

Awaiting one call after another is sequential: each starts only after the previous one finished. When the operations do not depend on each other, start them all and then await them together with Task.WhenAll:

using System;
using System.Diagnostics;
using System.Threading.Tasks;

class Program
{
    static async Task<int> FetchStockAsync(string item, int ms)
    {
        await Task.Delay(ms);   // simulated request
        return item.Length * 10;
    }

    static async Task RunAsync()
    {
        var sw = Stopwatch.StartNew();
        int a = await FetchStockAsync("apples", 300);
        int b = await FetchStockAsync("pears", 300);
        int c = await FetchStockAsync("plums", 300);
        Console.WriteLine("Sequential: " + (a + b + c) + " units in ~" + sw.ElapsedMilliseconds / 100 * 100 + " ms");

        sw.Restart();
        Task<int> ta = FetchStockAsync("apples", 300);   // all three start now
        Task<int> tb = FetchStockAsync("pears", 300);
        Task<int> tc = FetchStockAsync("plums", 300);
        int[] results = await Task.WhenAll(ta, tb, tc);
        Console.WriteLine("Concurrent: " + (results[0] + results[1] + results[2]) + " units in ~" + sw.ElapsedMilliseconds / 100 * 100 + " ms");
    }

    static void Main()
    {
        RunAsync().GetAwaiter().GetResult();
    }
}

Example output:

Sequential: 160 units in ~900 ms
Concurrent: 160 units in ~300 ms

The sequential version takes the sum of the three waits, the concurrent one about as long as the slowest. Task.WhenAll returns the results in the same order as the tasks you passed, regardless of which finished first. It works with a list too, which is the usual shape for "fetch every item": await Task.WhenAll(ids.Select(id => FetchAsync(id))).

Task.WhenAny is the counterpart that completes as soon as the first task does, useful for timeouts and "first answer wins".

Exceptions in async code

An exception thrown inside an async method is stored in the returned task and rethrown when the task is awaited, so an ordinary try/catch around the await works:

using System;
using System.Threading.Tasks;

class Program
{
    static async Task<string> LoadProfileAsync(int userId)
    {
        await Task.Delay(50);
        if (userId <= 0) throw new ArgumentOutOfRangeException(nameof(userId));
        return "profile " + userId;
    }

    static async Task RunAsync()
    {
        Task<string> task = LoadProfileAsync(-1);   // no exception yet
        Console.WriteLine("Task created, completed yet: " + task.IsCompleted);

        try
        {
            await task;                              // rethrown here
        }
        catch (ArgumentOutOfRangeException e)
        {
            Console.WriteLine("Caught " + e.GetType().Name + " for " + e.ParamName);
        }

        Task<string> ok = LoadProfileAsync(7);
        Task<string> bad = LoadProfileAsync(0);
        Task<string[]> all = Task.WhenAll(ok, bad);
        try
        {
            await all;
        }
        catch (ArgumentOutOfRangeException)
        {
            Console.WriteLine("WhenAll rethrew the first failure");
            Console.WriteLine("All failures: " + all.Exception.InnerExceptions.Count);
            Console.WriteLine("The other task still succeeded: " + ok.Result);
        }
    }

    static void Main()
    {
        RunAsync().GetAwaiter().GetResult();
    }
}

Output:

Task created, completed yet: False
Caught ArgumentOutOfRangeException for userId
WhenAll rethrew the first failure
All failures: 1
The other task still succeeded: profile 7

Calling LoadProfileAsync(-1) did not throw: the exception lives in the task until something awaits it. A task that nobody ever awaits hides its exception entirely, which is one more reason to always await what you start. With WhenAll, await rethrows the first exception, while the combined task's Exception property (an AggregateException) holds all of them. Reading ok.Result is fine there because ok has already completed.

async void: only for event handlers

An async method can also return void. Avoid it everywhere except event handlers:

// Bad: the caller cannot await it or catch its exceptions.
static async void SaveAsync(Order order)
{
    await db.InsertAsync(order);   // if this throws, the process may crash
}

// Good: return Task, so callers can await and handle errors.
static async Task SaveAsync(Order order)
{
    await db.InsertAsync(order);
}

// Acceptable: an event handler must return void.
private async void SaveButton_Click(object sender, EventArgs e)
{
    try { await SaveAsync(currentOrder); }
    catch (Exception ex) { ShowError(ex); }
}

With async void there is no task to await, so the caller carries on before the work is done, and an exception thrown inside is raised directly on the synchronization context (or the thread pool), where no caller's try/catch can reach it. In a console or server app, that usually terminates the process. Inside an async void event handler, catch everything yourself.

A related mistake is calling an async method without await. The compiler warns (CS4014), and the method runs in the background with nothing observing its result or its errors.

Deadlocks from .Result and .Wait()

Blocking on a task with .Result or .Wait() is where async code most often goes wrong. In an application with a synchronization context (WinForms, WPF, MAUI, classic ASP.NET), the sequence is:

The UI thread calls GetDataAsync().Result and blocks, waiting for the task.
Inside GetDataAsync, an await finishes. By default its continuation must run on the context it started on: the UI thread.
The UI thread is blocked in step 1, so the continuation never runs, so the task never completes, so step 1 never ends.

The app freezes with no exception. Console apps and ASP.NET Core have no such context, which is why the same code works in a test program and hangs in a desktop app. The fixes:

Use await all the way up the call chain instead of blocking ("async all the way"). Event handlers can be async void for this purpose.
In library code that does not need to return to the caller's context, write await SomethingAsync().ConfigureAwait(false);. The continuation then runs on the thread pool instead of the captured context, and the library skips an unnecessary thread switch. It only protects a blocking caller if every await in the chain does the same, so treat it as good library hygiene, not as a fix for .Result.

Application code in ASP.NET Core does not need ConfigureAwait(false), since there is no context to return to.

Common mistakes

Awaiting independent calls one by one. Start them, then await Task.WhenAll(...).
async void methods. Return Task; keep async void for event handlers.
.Result and .Wait() in UI or classic ASP.NET code. They deadlock; await instead.
Forgetting await. The work runs unobserved and its exceptions disappear.
Wrapping I/O in Task.Run. An async API such as File.ReadAllTextAsync or HttpClient.GetStringAsync already frees the thread; Task.Run only adds a thread pool hop.
Assuming async means "runs on another thread". It means "can pause without blocking". Use Task.Run for CPU-bound work.

Frequently Asked Questions

How do async and await work in C#?

Marking a method async lets it use await. When the method reaches await on a task that has not finished, it returns to its caller immediately, handing back a Task that represents the rest of the work. When the awaited operation completes, the method resumes after the await. No thread sits blocked while it waits.

What is the difference between Task and Task<T>?

Task represents an operation that produces no value, the async version of a void method. Task<T> represents one that produces a T: await on a Task<int> gives you the int. An async method declared async Task<int> just writes return 42;, and the compiler wraps it in the task.

How do I run multiple async operations at the same time?

Start them all first, then await them together: var a = GetUserAsync(); var b = GetOrdersAsync(); await Task.WhenAll(a, b);. Writing await GetUserAsync(); await GetOrdersAsync(); runs them one after another, so the total time is the sum instead of the longest one.

Why is async void bad in C#?

An async void method cannot be awaited, so the caller does not know when it finishes, and an exception thrown inside it cannot be caught by the caller: it is raised on the synchronization context and usually crashes the process. Return Task instead. async void exists only for event handlers, whose signature requires void.

Why does .Result or .Wait() cause a deadlock?

In an app with a synchronization context (WinForms, WPF, classic ASP.NET), .Result blocks the UI or request thread while the awaited method's continuation waits to run on that same thread. Each waits for the other forever. Use await all the way up instead of blocking, and use ConfigureAwait(false) inside library code.

Can Main be async in C#?

Yes, since C# 7.1: static async Task Main() or static async Task<int> Main(). Top-level statements (C# 9) can use await directly. In older code, the equivalent is calling MainAsync().GetAwaiter().GetResult() from a normal Main, which is safe there because a console app has no synchronization context.

Related concepts