
## 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.

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


## Table of Contents

1. [Introduction](#introduction)
2. [Enable Text Compression](#enable-text-compression)
3. [Reduce Unused CSS](#reduce-unused-css)
4. [Reduce Unused JavaScript](#reduce-unused-javascript)
5. [Color Contrast Checker](#color-contrast-checker)
6. [Browser Cache - Disk Cache](#browser-cache---disk-cache)
7. [Conclusion](#conclusion)

## Introduction

Google Lighthouse is a powerful tool for auditing website performance, accessibility, and best practices. This post covers a few quick wins to improve your Lighthouse score.

## Enable Text Compression

```
const compression = require('compression');
app.use(compression());
```

## Reduce Unused CSS

Make sure all CSS is minified as a bundle.

## Reduce Unused JavaScript

Defer loading scripts for Google Ads or Google Analytics.

## Color Contrast Checker

https://coolors.co/contrast-checker/000000-08a045

## Browser Cache - Disk Cache

```
res.set('Cache-control', `public, max-age=${period}`);
```

## Conclusion

By applying these Lighthouse recommendations — enabling text compression, reducing unused CSS and JavaScript, checking color contrast, and setting proper browser cache headers — you can significantly improve your website's performance score.


Tips and techniques for improving website performance using Google Lighthouse recommendations, including text compression, reducing unused CSS and JavaScript, and browser caching.

Performance

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

WebSite Performance Improvement - Lighthouse

Performance

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

WebSite Performance Improvement - Lighthouse

Subscribe for Updates