async and await

The previous lesson left you holding tasks and collecting results by hand. Two keywords turn that into code that reads top to bottom like any other method.

await means "I need this result before I continue". If the work is not finished, your method stops there and gives the thread back. When the result arrives, your method picks up on the next line with all its local variables intact.

async marks a method as one that contains awaits. It permits the keyword and lets the compiler rewrite the method into something that can pause and resume. It does not, by itself, make anything asynchronous.

public class CheckoutService
{
    private readonly IOrderStore _orders;
    private readonly IStockService _stock;
    private readonly IEmailSender _email;

    public CheckoutService(IOrderStore orders, IStockService stock, IEmailSender email)
    {
        _orders = orders;
        _stock = stock;
        _email = email;
    }

    public async Task<string> ConfirmAsync(int orderId)
    {
        Order? order = await _orders.FindAsync(orderId);

        if (order is null)
        {
            return "No such order.";
        }

        bool inStock = await _stock.IsAvailableAsync(order.Sku, order.Quantity);

        if (!inStock)
        {
            return $"Order {order.Reference} is waiting for stock.";
        }

        order.Confirm();
        await _orders.SaveAsync(order);
        await _email.SendConfirmationAsync(order);

        return $"Order {order.Reference} confirmed.";
    }
}

• Read it without the awaits and it is an ordinary method: find, check, confirm, save, notify. That readability is the whole point of the feature.
• Each await is a place the method may pause. At each one, if the work is not already finished, the thread is released and the rest of the method is scheduled to run when the result arrives.
• Local variables — order, inStock — survive across those pauses. The compiler moves them somewhere that outlives a single stretch of execution.
• The if statements, the early return and the string interpolation all behave exactly as they would in a synchronous method. Ordinary control flow works.
• The signature is async Task<string>. The caller receives a task immediately, and the string appears in it later.

Once a method is asynchronous, its callers should be too, right up to the point where something outside your code is in charge. That point is a controller action, a hosted service, a message handler, or Main.

Those entry points are all able to be asynchronous. ASP.NET Core awaits your controller action. A modern Main may be declared async Task. There is nearly always somewhere sensible to hand the task to.

The alternative — an asynchronous method called from a synchronous one that blocks for the answer — reintroduces exactly the cost you were removing, and adds a failure mode.

// Wrong. Blocks the calling thread and risks a deadlock.
public string Confirm(int orderId)
{
    return ConfirmAsync(orderId).Result;
}

// Also wrong. Wait() has the same problems as Result.
public void Notify(Order order)
{
    _email.SendConfirmationAsync(order).Wait();
}

// Right. The asynchrony is passed up to the caller.
[HttpPost("orders/{orderId}/confirm")]
public async Task<IActionResult> Confirm(int orderId)
{
    string outcome = await _checkout.ConfirmAsync(orderId);

    return Ok(outcome);
}

• The first method turns an asynchronous call back into a blocking one. The thread is held for the whole operation, so nothing was saved — and in some hosts it never finishes at all.
• Wait() is the same mistake without a return value. So is GetAwaiter().GetResult(), which differs only in how it reports exceptions.
• The third version changes the return type to Task<IActionResult> and awaits. The framework is happy to be handed a task; that is what it expects.
• Notice that fixing this is usually a matter of propagating the signature change, not restructuring logic. It is tedious in a large codebase, which is why starting asynchronous is easier than converting later.

You can write async void. The compiler allows it. It exists for one reason: event handlers have a signature that returns void, and you sometimes need to await inside one.

Everywhere else it is a trap, because an async void method returns nothing that can be observed. There is no task, so there is nothing to await, nothing to know it finished, and nowhere for an exception to go.

An exception thrown after the first await in an async void method cannot be caught by the caller. It surfaces as an unhandled exception on whatever thread happened to be running the continuation, which in many hosts brings the process down.

// Dangerous. If archiving throws, the caller cannot catch it.
public async void ArchiveOrder(Order order)
{
    await _archive.StoreAsync(order);
}

// Correct. The caller can await it, and can catch failures.
public async Task ArchiveOrderAsync(Order order)
{
    await _archive.StoreAsync(order);
}

// The caller's view of each:
try
{
    ArchiveOrder(order);            // returns instantly; exceptions escape entirely
    await ArchiveOrderAsync(order); // waits, and a failure lands in the catch below
}
catch (Exception ex)
{
    _logger.LogError(ex, "Archiving order {Reference} failed.", order.Reference);
}

• The only difference in the declarations is void versus Task. That one word decides whether failure is reportable.
• The call to ArchiveOrder returns as soon as the first await is reached. The try block is finished long before the archiving is. Its catch can never see the failure.
• The call to ArchiveOrderAsync is awaited, so the catch is still active when the failure surfaces. The exception is delivered at the await.
• The structured logging call passes order.Reference as a parameter rather than building the message by hand, which keeps the reference searchable in the logs.