Code review: a service method returns null when an order is not found, reports errors through two out parameters, returns its internal List<Order> directly, and is called from async code. How would you redesign its return types, and what return options does C# give you?

1. Why out and ref cannot cross await

An async method is compiled into a state machine whose locals are hoisted into fields so they survive across await. An out or ref parameter is a managed pointer to the caller's storage — possibly a stack slot. Managed pointers cannot be stored in heap objects (the state machine is a heap object once the method suspends), because the stack frame they point to may be gone. So the language forbids ref, in and out parameters on async methods and iterators (CS1988). This is the fundamental reason "Try" methods have no async equivalent and async APIs return tuples, records or nullable results instead.

2. Nullable reference types as the contract for "not found"

With <Nullable>enable</Nullable>, Task<Order?> tells callers and the compiler that null is possible. Callers who dereference without checking get warning CS8602, which teams usually promote to an error. The return type also flows into tooling: OpenAPI generators can mark the response as nullable, and static analysis follows null-state through the code.

The limitation: NRT is compile-time only. Callers compiled without nullable context, reflection, or deserialisers can still pass or receive null. Public boundaries still need guards.

3. Result types — what they are and how to implement one

A result type makes expected failures part of the return type instead of side channels or exceptions:

public abstract record OrderError
{
    public sealed record NotFound(int OrderId) : OrderError;
    public sealed record AlreadyShipped(int OrderId, DateOnly ShippedOn) : OrderError;
    public sealed record NotOwned(int OrderId) : OrderError;
}

public readonly record struct Result<T, TError>(T? Value, TError? Error)
{
    public bool IsSuccess => Error is null;
    public static Result<T, TError> Ok(T value) => new(value, default);
    public static Result<T, TError> Fail(TError error) => new(default, error);
}

The caller then pattern-matches:

return result.Error switch
{
    null                          => TypedResults.Ok(result.Value!.ToDto()),
    OrderError.NotFound           => TypedResults.NotFound(),
    OrderError.AlreadyShipped e   => TypedResults.Conflict(e),
    OrderError.NotOwned           => TypedResults.NotFound(),   // don't leak existence
    _                             => throw new UnreachableException()
};

Trade-offs: result types add ceremony and must be propagated manually through layers (C# has no ? operator like Rust). Libraries such as OneOf, ErrorOr and FluentResults reduce boilerplate. Use them for business outcomes; don't wrap every database call.

4. Tuples vs records

• ValueTuple ((bool Found, Order? Order)) is a mutable struct with fields Item1, Item2; the names are compile-time only (stored in TupleElementNamesAttribute), so they disappear in reflection and serialisation. Great for private helpers and deconstruction.
• A record (or record struct) has real named properties, value equality, a good ToString, and can evolve by adding properties. Prefer records for anything public or serialised.

5. Returning collections safely

Returning _orders directly hands out the same object. Options:

For EF Core, return projections (Select into DTOs) rather than tracked entities, so callers cannot accidentally change tracked state or trigger lazy loading.

6. Task<T> vs ValueTask<T>

• Task<T> is the default: it can be awaited multiple times, stored, and combined with WhenAll.
• ValueTask<T> avoids an allocation when the result is usually synchronous (e.g. a cache hit). It must be awaited exactly once and not used concurrently. Use it only on measured hot paths, and keep public service APIs on Task<T> unless profiling justifies the change.

7. ref returns

ref T / ref readonly T return a reference to existing storage (an array element, a struct field). CollectionsMarshal.GetValueRefOrAddDefault and Span<T> indexers use them. They avoid copying large structs and allow in-place updates, but they are a low-level tool for libraries and hot paths, not service APIs.

Try it yourself

1. Try to declare async Task<Order> GetAsync(int id, out string error) and read CS1988.
2. Return _orders as IReadOnlyList<Order>, cast it back to List<Order> in the caller and Clear() it — then switch to AsReadOnly() or ToArray().
3. Implement a small OrderError hierarchy and a switch expression that maps it to TypedResults.

namespace Orders;

public sealed record Order(int Id, string Customer, decimal Total);
public sealed record PlaceOrder(string Customer, decimal Total);

public sealed record Result<T>
{
    public T? Value { get; private init; }
    public string? Error { get; private init; }
    public bool IsSuccess => Error is null;

    public static Result<T> Ok(T value) => new() { Value = value };
    public static Result<T> Fail(string error) => new() { Error = error };
}

public sealed class OrderService
{
    private readonly List<Order> _orders = [new(1, "Ada", 120m)];
    private readonly Lock _gate = new();          // C# 13 / .NET 9 Lock type

    // Absence is explicit and async-friendly
    public Task<Order?> FindOrderAsync(int id, CancellationToken ct = default)
    {
        lock (_gate)
        {
            return Task.FromResult(_orders.FirstOrDefault(o => o.Id == id));
        }
    }

    // Expected failures in a result, not out parameters
    public Task<Result<Order>> PlaceOrderAsync(PlaceOrder cmd, CancellationToken ct = default)
    {
        if (cmd.Total <= 0)
            return Task.FromResult(Result<Order>.Fail("Total must be positive"));

        lock (_gate)
        {
            var order = new Order(_orders.Count + 1, cmd.Customer, cmd.Total);
            _orders.Add(order);
            return Task.FromResult(Result<Order>.Ok(order));
        }
    }

    // No leaking of internal state: a snapshot copy
    public IReadOnlyList<Order> GetRecent()
    {
        lock (_gate) { return _orders.TakeLast(10).ToArray(); }
    }

    // Tuple for an internal helper
    internal (int Count, decimal Sum) Totals()
    {
        lock (_gate) { return (_orders.Count, _orders.Sum(o => o.Total)); }
    }
}

// Usage at the HTTP edge (Minimal API):
// app.MapGet("/orders/{id:int}", async (int id, OrderService s, CancellationToken ct) =>
//     await s.FindOrderAsync(id, ct) is { } order ? Results.Ok(order) : Results.NotFound());