
## Table of Contents

1. [Why This Matters](#why-this-matters)
2. [Task vs ValueTask in One Minute](#task-vs-valuetask-in-one-minute)
3. [Three-Tier API Rule of Thumb](#three-tier-api-rule-of-thumb)
4. [Scenario 1: Cache-First Read (Use ValueTask in Service)](#scenario-1-cache-first-read-use-valuetask-in-service)
5. [Scenario 2: Always Network I/O (Use Task)](#scenario-2-always-network-io-use-task)
6. [Scenario 3: Fan-Out Aggregation (Use Task for Combinators)](#scenario-3-fan-out-aggregation-use-task-for-combinators)
7. [Common Mistakes and Fixes](#common-mistakes-and-fixes)
8. [Decision Checklist](#decision-checklist)
9. [Summary](#summary)

---

## Why This Matters

In C#, `Task<T>` is the default async return type. It is simple, flexible, and safe for most app code.

`ValueTask<T>` exists for performance-sensitive paths where methods complete synchronously very often (for example, cache hits or buffered reads). It can avoid per-call `Task` allocations on the fast path.

The key point: `ValueTask<T>` is not a replacement for `Task<T>`.

## Task vs ValueTask in One Minute

- `Task<T>`:

  - Reference type
  - Easy to compose (`Task.WhenAll`, `Task.WhenAny`)
  - Safe to await multiple times
  - Usually the best default

- `ValueTask<T>`:
  - Value type (`struct`)
  - Can avoid allocation when result is immediately available
  - Single-consumption by design (do not await the same instance twice)
  - Better for hot paths with frequent synchronous completion

## Three-Tier API

In a typical API tiering:

- Controller/API layer
- Service/business layer
- Data/repository layer

Use this mental model:

| Layer           | Default Choice              | Why                                                 |
| --------------- | --------------------------- | --------------------------------------------------- |
| Controller/API  | `Task<T>`                   | One call per request, simplicity is more important  |
| Service         | `Task<T>` or `ValueTask<T>` | Use `ValueTask<T>` only if sync fast path is common |
| Repository/Data | Usually `Task<T>`           | DB/HTTP/file I/O is usually truly async             |

## Scenario 1: Cache-First Read (Use ValueTask in Service)

This is the best case for `ValueTask<T>` in a three-tier API.

- Most reads are cache hits (synchronous)
- Cache miss falls back to repository async I/O
- Service can return `ValueTask<T>` to avoid allocations on hot cache hits

### Controller (API Layer)

```csharp
[ApiController]
[Route("api/products")]
public class ProductsController : ControllerBase
{
    private readonly ProductService _service;

    public ProductsController(ProductService service) => _service = service;

    [HttpGet("{id:int}")]
    public async Task<ActionResult<ProductDto>> GetById(int id, CancellationToken ct)
    {
        var product = await _service.GetByIdAsync(id, ct);
        return product is null ? NotFound() : Ok(product);
    }
}
```

Controller still returns `Task<ActionResult<T>>` for readability and consistency.

### Service (Business Layer)

```csharp
public sealed class ProductService
{
    private readonly IMemoryCache _cache;
    private readonly IProductRepository _repo;

    public ProductService(IMemoryCache cache, IProductRepository repo)
    {
        _cache = cache;
        _repo = repo;
    }

    // Good ValueTask use: high cache hit ratio means frequent sync completion.
    public async ValueTask<ProductDto?> GetByIdAsync(int id, CancellationToken ct)
    {
        string cacheKey = $"product:{id}";

        if (_cache.TryGetValue(cacheKey, out ProductDto? cached))
            return cached; // synchronous fast path, no Task allocation

        var product = await _repo.GetByIdAsync(id, ct);
        if (product is not null)
            _cache.Set(cacheKey, product, TimeSpan.FromMinutes(10));

        return product;
    }
}
```

### Repository (Data Layer)

```csharp
public interface IProductRepository
{
    Task<ProductDto?> GetByIdAsync(int id, CancellationToken ct);
}

public sealed class ProductRepository(AppDbContext db) : IProductRepository
{
    public async Task<ProductDto?> GetByIdAsync(int id, CancellationToken ct)
    {
        return await db.Products
            .Where(p => p.Id == id)
            .Select(p => new ProductDto(p.Id, p.Name, p.Price))
            .FirstOrDefaultAsync(ct);
    }
}
```

Repository stays `Task<T>` because database queries are real async I/O.

## Scenario 2: Always Network I/O (Use Task)

If every call goes to external HTTP/database/file I/O, `ValueTask<T>` usually provides no measurable benefit.

### Controller

```csharp
[HttpGet("{id:int}/shipping")]
public async Task<ActionResult<ShippingQuoteDto>> GetShippingQuote(int id, CancellationToken ct)
{
    var quote = await _service.GetShippingQuoteAsync(id, ct);
    return Ok(quote);
}
```

### Service

```csharp
public sealed class ShippingService(IShippingClient client)
{
    // Always network call -> Task<T> is the better default.
    public async Task<ShippingQuoteDto> GetShippingQuoteAsync(int orderId, CancellationToken ct)
    {
        return await client.GetQuoteAsync(orderId, ct);
    }
}
```

### Data/Client

```csharp
public interface IShippingClient
{
    Task<ShippingQuoteDto> GetQuoteAsync(int orderId, CancellationToken ct);
}

public sealed class ShippingClient(HttpClient http) : IShippingClient
{
    public async Task<ShippingQuoteDto> GetQuoteAsync(int orderId, CancellationToken ct)
    {
        using var response = await http.GetAsync($"/quotes/{orderId}", ct);
        response.EnsureSuccessStatusCode();

        var result = await response.Content.ReadFromJsonAsync<ShippingQuoteDto>(cancellationToken: ct);
        return result ?? throw new InvalidOperationException("Empty quote response");
    }
}
```

No synchronous fast path means no real `ValueTask<T>` advantage.

## Scenario 3: Fan-Out Aggregation (Use Task for Combinators)

If you need `Task.WhenAll`/`Task.WhenAny`, `Task<T>` is usually the cleanest choice.

### Controller

```csharp
[HttpGet("dashboard/{customerId:int}")]
public async Task<ActionResult<DashboardDto>> GetDashboard(int customerId, CancellationToken ct)
{
    var dashboard = await _service.BuildDashboardAsync(customerId, ct);
    return Ok(dashboard);
}
```

### Service

```csharp
public sealed class DashboardService(
    IOrderRepository orders,
    IInvoiceRepository invoices,
    IRecommendationClient recommendations)
{
    public async Task<DashboardDto> BuildDashboardAsync(int customerId, CancellationToken ct)
    {
        Task<IReadOnlyList<OrderDto>> ordersTask = orders.GetRecentAsync(customerId, ct);
        Task<IReadOnlyList<InvoiceDto>> invoicesTask = invoices.GetOpenAsync(customerId, ct);
        Task<IReadOnlyList<ProductDto>> recTask = recommendations.GetTopAsync(customerId, ct);

        await Task.WhenAll(ordersTask, invoicesTask, recTask);

        return new DashboardDto(
            await ordersTask,
            await invoicesTask,
            await recTask);
    }
}
```

### Repository/Client

```csharp
public interface IOrderRepository
{
    Task<IReadOnlyList<OrderDto>> GetRecentAsync(int customerId, CancellationToken ct);
}

public interface IInvoiceRepository
{
    Task<IReadOnlyList<InvoiceDto>> GetOpenAsync(int customerId, CancellationToken ct);
}

public interface IRecommendationClient
{
    Task<IReadOnlyList<ProductDto>> GetTopAsync(int customerId, CancellationToken ct);
}
```

You can convert `ValueTask<T>` using `.AsTask()`, but if combinators are central, returning `Task<T>` keeps code straightforward.

## Common Mistakes and Fixes

### Mistake 1: Replacing all `Task<T>` with `ValueTask<T>`

Wrong because methods that always suspend gain little and become harder to reason about. Also, below reasons are also can't just replace `Task<T>` to `ValutTask<T>`, for example cannot await it concurrently.

Fix: keep `Task<T>` as default; optimize only proven hot paths.

### Mistake 2: Awaiting the same `ValueTask<T>` twice

```csharp
ValueTask<int> vt = service.GetCountAsync(ct);
int a = await vt;
int b = await vt; // wrong
```

Fix:

```csharp
Task<int> t = service.GetCountAsync(ct).AsTask();
int a = await t;
int b = await t; // safe
```

### Mistake 3: Forcing `ValueTask<T>` in controllers

Controller actions are not usually hot loops; one task allocation per request is negligible compared to pipeline cost.

Fix: prefer `Task<ActionResult<T>>` for controller actions.

## Decision Checklist

Use `ValueTask<T>` only when all are true:

- Method frequently completes synchronously
- It is in a hot path (high call frequency)
- You measured allocation/GC pressure worth optimizing
- Callers can consume result immediately (single-await pattern)

Use `Task<T>` when any of these are true:

- Operation is almost always real async I/O
- You need `Task.WhenAll`/`Task.WhenAny` composition
- You need to await multiple times or pass work around
- Simplicity and maintainability are higher priority

## Summary

`Task<T>` is the right default for most three-tier API code.

`ValueTask<T>` is a targeted optimization tool for hot paths with frequent synchronous completion, especially in service-layer cache-aside flows.

Start with `Task<T>`, measure with profiling, then introduce `ValueTask<T>` only where it removes meaningful allocation overhead.


Understand when to use Task vs ValueTask in ASP.NET Core three-tier APIs, with practical examples for cache-heavy, always-I/O, and batch aggregation scenarios.

ValueTask

C# ValueTask vs Task in Three-Tier APIs — When to Use Each

Subscribe for Updates