
## Table of Contents

1. [Introduction](#introduction)
2. [Why Cancellation Matters in Web APIs](#why-cancellation-matters-in-web-apis)
3. [How CancellationToken Works in ASP.NET Core](#how-cancellationtoken-works-in-aspnet-core)
4. [Best Practices by Layer](#best-practices-by-layer)
5. [Demo: Detecting Cancellation in Practice](#demo-detecting-cancellation-in-practice)
6. [Testing Cancellation: Client Scenarios](#testing-cancellation-client-scenarios)
7. [Summary Checklist](#summary-checklist)
8. [References](#references)

---

## Introduction

Handling request cancellation is essential for building robust, scalable ASP.NET Core Web APIs. This post covers the best practices for using `CancellationToken`—from API to service and data layers—so your app can respond quickly to client disconnects and avoid wasted work.

## Why Cancellation Matters in Web APIs

When a client disconnects (closes a browser tab, navigates away, or cancels a request), the server should stop any unnecessary work. ASP.NET Core provides a `CancellationToken` for every request, allowing you to:

- Free up resources immediately
- Avoid running expensive or irreversible operations
- Improve scalability and responsiveness

## How CancellationToken Works in ASP.NET Core

- ASP.NET Core injects a `CancellationToken` into every controller action.
- The token is triggered if the client disconnects or cancels the request.
- Many async APIs (like `Task.Delay`, `HttpClient`, EF Core) already respect the token.

## Best Practices by Layer

**Based on expert guidance:**

- **API Layer:**
  - Never check the token manually. ASP.NET injects and manages it for you.
  - Only catch `OperationCanceledException` at the top level if you want to log or return a custom status code.
- **Service Layer:**
  - Add manual checks only:
    - Before starting slow or critical work (in case the client already disconnected)
    - Between long-running steps or before irreversible actions (e.g., sending an email)
  - Use `cancellationToken.ThrowIfCancellationRequested();` where appropriate.
  - Never check manually. Most async APIs (EF Core, `Task.Delay`, `HttpClient`) already handle the token.

**Mental test:**
> "Am I doing slow work that the framework can't see?" If yes, add a check. If not, just pass the token.

## Demo: Detecting Cancellation in Practice
## IsCancellationRequested vs ThrowIfCancellationRequested

When should you use `cancellationToken.IsCancellationRequested` instead of `ThrowIfCancellationRequested()`?

- Use **IsCancellationRequested** when you want to check for cancellation and exit gracefully—without throwing an exception. This is ideal for loops, background services, or cleanup code where you can simply return or break.
- Use **ThrowIfCancellationRequested()** when you want to immediately abort execution and bubble up an `OperationCanceledException`. This is best for service/business logic where you want to stop work and let higher layers handle the cancellation (logging, status code, etc.).

**Summary:**
- Use `IsCancellationRequested` for silent, graceful exits.
- Use `ThrowIfCancellationRequested()` to enforce immediate cancellation and propagate the exception.

**Example:**

```csharp
// Graceful exit in a loop
while (!cancellationToken.IsCancellationRequested)
{
  await DoWorkAsync();
}
// Immediate abort in business logic
cancellationToken.ThrowIfCancellationRequested();
DoCriticalWork();
```

### Backend API Example

```csharp
[HttpGet("slow-report")]
public async Task<IActionResult> GetSlowReport(CancellationToken cancellationToken)
{
    _logger.LogInformation(">>> Request started");
    cancellationToken.ThrowIfCancellationRequested();
    try
    {
        // Step 1 — simulate slow DB query
        _logger.LogInformation(">>> Starting DB query...");
        await Task.Delay(5_000, cancellationToken);
        _logger.LogInformation(">>> DB query done");

        // Step 2 — simulate heavy CPU work
        _logger.LogInformation(">>> Building report...");
        await Task.Delay(5_000, cancellationToken);
        _logger.LogInformation(">>> Report built");

        return Ok(new { message = "Done" });
    }
    catch (OperationCanceledException)
    {
        _logger.LogWarning(">>> REQUEST CANCELLED — client disconnected");
        return StatusCode(499);
    }
}
```

- If the client cancels after 2 seconds, logs show:
  - `>>> Request started`
  - `>>> Starting DB query...`
  - `>>> REQUEST CANCELLED — client disconnected` (never reaches "DB query done")

## Testing Cancellation: Client Scenarios

### 1. Manual Cancellation with HttpClient

```csharp
using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(2));
using var http = new HttpClient();
try
{
    var response = await http.GetAsync("https://localhost:7001/api/slow-report", cts.Token);
    Console.WriteLine($"Completed: {response.StatusCode}");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Cancelled — simulates client disconnect");
}
```

- This approach is repeatable and precise for testing.

### 2. Browser Tab Close / Navigation

```javascript
fetch('https://localhost:7001/api/slow-report')
  .then(r => r.json())
  .then(console.log);
// Now close the tab — ASP.NET Core detects the TCP connection drop and fires the CancellationToken
```

### 3. UI Demo (Sample Client)

The included demo client lets you:
- Start a long-running request
- Cancel manually or simulate a tab close
- View real-time logs of cancellation events

## Summary Checklist

- [x] Pass the `CancellationToken` through all async APIs
- [x] Only check/cancel in the service layer when needed
- [x] Never check in API or data layers, because framework code already handler
- [x] Log and handle `OperationCanceledException` for observability

## References

- [Microsoft Docs: Cancellation in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/cancellation)

---

For more C# and ASP.NET Core tips, check out other posts in this category!


Learn the best practices for using CancellationToken in ASP.NET Core Web APIs, with real-world code samples, client/server demos, and practical guidance for robust cancellation handling.

C# CancellationToken Best Practices for Web API


## Table of Contents

1. [Pattern Matching (C# 7–13)](#pattern-matching-c-7--13)
2. [Records (C# 9.0 / 10.0)](#records-c-90--100)
3. [`required` Members (C# 11)](#required-members-c-11)
4. [Collection Expressions (C# 12)](#collection-expressions-c-12)
5. [Primary Constructors for Classes (C# 12)](#primary-constructors-for-classes-c-12)
6. [`file`-Scoped Types (C# 11)](#file-scoped-types-c-11)
7. [`global using` & Implicit Usings (C# 10)](#global-using--implicit-usings-c-10)
8. [Raw String Literals (C# 11)](#raw-string-literals-c-11)
9. [`params` Collections (C# 13)](#params-collections-c-13)
10. [Other Notable Features](#other-notable-features)

---

## Pattern Matching (C# 7–13)

**Pattern matching** lets you test a value against a shape, type, or condition — and extract data in the process. It has evolved significantly across C# versions, from simple type checks to complex deconstruction.

### Type Patterns (C# 7.0)

```csharp
// Test and cast in one step
object obj = GetValue();

if (obj is string text)
    Console.WriteLine(text.Length); // text is already a string

if (obj is int number and number > 0)
    Console.WriteLine($"Positive: {number}");

// Switch with type patterns
string Describe(object value) => value switch
{
    int i => $"Integer: {i}",
    string s => $"String: {s}",
    null => "null",
    _ => $"Unknown: {value.GetType().Name}"
};
```

### Property Patterns (C# 8.0)

```csharp
// Match on properties of an object
string GetShippingCost(Order order) => order switch
{
    { Total: > 100, IsPremium: true } => "Free",
    { Total: > 100 } => "$5.00",
    { Weight: > 50 } => "$25.00",
    _ => "$10.00"
};

// Nested property patterns
bool IsLocalCustomer(Order order) => order is
{
    Customer.Address.Country: "US",
    Customer.Address.State: "CA"
};
```

### Positional Patterns (C# 8.0)

```csharp
// Works with types that have Deconstruct or are records/tuples
public record Point(int X, int Y);

string Classify(Point point) => point switch
{
    (0, 0) => "Origin",
    (var x, 0) => $"On X-axis at {x}",
    (0, var y) => $"On Y-axis at {y}",
    (var x, var y) when x == y => $"On diagonal at ({x}, {y})",
    _ => "Elsewhere"
};
```

### Relational & Logical Patterns (C# 9.0)

```csharp
// Relational: <, >, <=, >=
string GetTemperatureCategory(double temp) => temp switch
{
    < 0 => "Freezing",
    >= 0 and < 15 => "Cold",
    >= 15 and < 25 => "Pleasant",
    >= 25 and < 35 => "Warm",
    >= 35 => "Hot"
};

// Logical: and, or, not
bool IsValidAge(int age) => age is >= 0 and <= 150;
bool IsNotNull(object? obj) => obj is not null;
bool IsWeekend(DayOfWeek day) => day is DayOfWeek.Saturday or DayOfWeek.Sunday;

// Combined
string Classify(int value) => value switch
{
    > 0 and < 10 => "Small positive",
    >= 10 and < 100 => "Medium positive",
    >= 100 => "Large positive",
    0 => "Zero",
    < 0 => "Negative"
};
```

### List Patterns (C# 11)

```csharp
// Match against array/list structure
int[] numbers = [1, 2, 3, 4, 5];

var result = numbers switch
{
    [] => "Empty",
    [var single] => $"Single: {single}",
    [var first, .., var last] => $"First: {first}, Last: {last}",
    [1, 2, ..] => "Starts with 1, 2",
    [.., 4, 5] => "Ends with 4, 5",
};

// Slice pattern with discard
bool IsValid(int[] data) => data is [> 0, .., > 0]; // first and last are positive

// With ReadOnlySpan<char> for string parsing
bool IsCsvHeader(ReadOnlySpan<char> line) => line switch
{
    ['#', ..] => false,        // comment line
    ['"', .., '"'] => true,    // quoted header
    _ => true
};
```

---

## Records (C# 9.0 / 10.0)

**Records** are reference types (or value types with `record struct`) that provide **value-based equality**, **immutability**, and **deconstruction** with minimal boilerplate.

```csharp
// Record class (reference type, C# 9.0)
public record OrderDto(int Id, string CustomerName, decimal Total);

// Record struct (value type, C# 10.0)
public readonly record struct Money(decimal Amount, string Currency);

// What you get for free:
// • Value-based Equals and GetHashCode
// • ToString (e.g., "OrderDto { Id = 1, CustomerName = Alice, Total = 99.99 }")
// • Deconstruction
// • with-expression for non-destructive mutation

var order = new OrderDto(1, "Alice", 99.99m);
var updated = order with { Total = 150m }; // new instance, only Total changed

var (id, name, total) = order; // deconstruction
```

### Record vs Class vs Struct

| Feature | `record` | `record struct` | `class` | `struct` |
|---|---|---|---|---|
| Equality | Value-based | Value-based | Reference-based | Value-based (slow) |
| Heap/Stack | Heap | Stack | Heap | Stack |
| `with` expression | ✓ | ✓ | ✗ | ✗ |
| Inheritance | ✓ | ✗ | ✓ | ✗ |
| `ToString` | Auto-generated | Auto-generated | `GetType().Name` | `GetType().Name` |
| Best for | DTOs, events, value objects | Small value objects | Complex entities | Low-level perf |

---

## `required` Members (C# 11)

Forces callers to set specific properties at construction time — compile-time enforcement.

```csharp
public class CreateOrderRequest
{
    public required string CustomerId { get; init; }
    public required List<OrderItemRequest> Items { get; init; }
    public string? Notes { get; init; }  // optional
}

// ✓ Must set required properties
var request = new CreateOrderRequest
{
    CustomerId = "cust-1",
    Items = [new("SKU-1", 2)]
};

// ✗ Compile error — CustomerId is required
var bad = new CreateOrderRequest
{
    Items = [new("SKU-1", 2)]
}; // CS9035: Required member 'CustomerId' must be set
```

Use `required` instead of constructor parameters when you want object-initializer syntax with compile-time safety.

---

## Collection Expressions (C# 12)

A concise syntax for creating collections — works with arrays, `List<T>`, `Span<T>`, `ImmutableArray<T>`, and more.

```csharp
// Before
int[] numbers = new int[] { 1, 2, 3 };
List<string> names = new List<string> { "Alice", "Bob" };
Span<int> span = stackalloc int[] { 1, 2, 3 };

// After (C# 12)
int[] numbers = [1, 2, 3];
List<string> names = ["Alice", "Bob"];
Span<int> span = [1, 2, 3];

// Empty collections
List<Order> orders = [];
int[] empty = [];

// Spread operator (..) — combine collections
int[] first = [1, 2, 3];
int[] second = [4, 5, 6];
int[] combined = [..first, ..second]; // [1, 2, 3, 4, 5, 6]

// Works with any target type that supports collection expressions
ImmutableArray<int> immutable = [1, 2, 3];
HashSet<string> set = ["a", "b", "c"];
```

---

## Primary Constructors for Classes (C# 12)

Classes can now have primary constructors — parameters are captured and available throughout the class.

```csharp
// Before
public class OrderService
{
    private readonly IOrderRepository _repo;
    private readonly ILogger<OrderService> _logger;

    public OrderService(IOrderRepository repo, ILogger<OrderService> logger)
    {
        _repo = repo;
        _logger = logger;
    }
}

// After (C# 12)
public class OrderService(IOrderRepository repo, ILogger<OrderService> logger)
{
    public async Task<Order?> GetByIdAsync(int id, CancellationToken ct)
    {
        logger.LogInformation("Fetching order {OrderId}", id);
        return await repo.GetByIdAsync(id, ct);
    }
}
```

**Note:** Primary constructor parameters are **not** `readonly` by default — see your clean-code guidelines for the full details.

---

## `file`-Scoped Types (C# 11)

A type visible **only within the file** where it's declared — perfect for hiding implementation details.

```csharp
// OrderService.cs

public class OrderService(IOrderRepository repo)
{
    public async Task<OrderResult> ProcessAsync(Order order, CancellationToken ct)
    {
        var validator = new OrderValidator();
        if (!validator.IsValid(order))
            return OrderResult.Invalid(validator.Errors);

        await repo.SaveAsync(order, ct);
        return OrderResult.Success(order);
    }
}

// Only visible in this file — won't pollute the namespace
file class OrderValidator
{
    public List<string> Errors { get; } = [];

    public bool IsValid(Order order)
    {
        if (order.Total <= 0)
            Errors.Add("Total must be positive");
        if (string.IsNullOrWhiteSpace(order.CustomerName))
            Errors.Add("Customer name is required");
        return Errors.Count == 0;
    }
}
```

---

## `global using` & Implicit Usings (C# 10)

```csharp
// GlobalUsings.cs — declare once, available everywhere in the project
global using System.Collections.Concurrent;
global using Microsoft.Extensions.Logging;
global using MyApp.Domain.Entities;
global using MyApp.Application.Interfaces;

// Implicit usings (.NET 6+ — enabled by default in .csproj)
// <ImplicitUsings>enable</ImplicitUsings>
// Automatically adds: System, System.Collections.Generic, System.Linq,
// System.Threading.Tasks, System.IO, etc.
```

---

## Raw String Literals (C# 11)

```csharp
// Multi-line strings without escape characters
string json = """
    {
        "name": "Alice",
        "age": 30,
        "orders": [
            { "id": 1, "total": 99.99 }
        ]
    }
    """;

// Interpolated raw strings — use $$ with {{ }}
string name = "Alice";
string jsonTemplate = $$"""
    {
        "name": "{{name}}",
        "timestamp": "{{DateTime.UtcNow:O}}"
    }
    """;
```

---

## `params` Collections (C# 13)

`params` now works with **any collection type**, not just arrays.

```csharp
// Before (C# 1.0 — arrays only)
public void Log(params string[] messages) { }

// After (C# 13 — any collection)
public void Log(params ReadOnlySpan<string> messages)
{
    foreach (var msg in messages)
        Console.WriteLine(msg);
}

public void Process(params IEnumerable<int> values) { }
public void Build(params List<string> items) { }

// Still called the same way
Log("hello", "world");
Process(1, 2, 3);
```

💡 `params ReadOnlySpan<T>` avoids the array allocation of `params T[]`.

---

## Other Notable Features

### `using` Declarations (C# 8.0)

No braces needed — automatically disposed at end of scope.

```csharp
// Before
using (var stream = File.OpenRead("data.txt"))
{
    // use stream
}

// After — disposed when the enclosing block (method, if, etc.) exits
using var stream = File.OpenRead("data.txt");
// use stream
```

### Switch Expressions (C# 8.0)

```csharp
string result = status switch
{
    OrderStatus.Pending => "Processing",
    OrderStatus.Shipped => "On the way",
    OrderStatus.Delivered => "Complete",
    _ => "Unknown"
};
```

### Null-Coalescing Assignment `??=` (C# 8.0)

```csharp
_cache ??= new Dictionary<string, int>();
```

### Target-Typed `new` (C# 9.0)

```csharp
Dictionary<string, List<int>> map = new(); // type inferred from left side
```

### File-Scoped Namespaces (C# 10)

```csharp
// Before
namespace MyApp.Services
{
    public class OrderService { }
}

// After — saves one level of indentation
namespace MyApp.Services;

public class OrderService { }
```

### Generic Attributes (C# 11)

```csharp
// Before — typeof required
[Validator(typeof(OrderValidator))]
public class Order { }

// After — generic attribute
[Validator<OrderValidator>]
public class Order { }
```

### `nameof` Scope Improvement (C# 11)

```csharp
// nameof works on method parameters in attributes
[return: NotNullIfNotNull(nameof(input))]
public static string? Process(string? input) => input?.Trim();
```

---

## Feature Version Quick Reference

| Feature | C# Version | .NET Version |
|---|---|---|
| Pattern matching (basic) | 7.0 | .NET Core 2.0 |
| `Span<T>`, `ref struct` | 7.2 | .NET Core 2.1 |
| Nullable reference types | 8.0 | .NET Core 3.0 |
| `using` declarations | 8.0 | .NET Core 3.0 |
| Switch expressions | 8.0 | .NET Core 3.0 |
| Default interface methods | 8.0 | .NET Core 3.0 |
| `IAsyncEnumerable<T>` | 8.0 | .NET Core 3.0 |
| Records | 9.0 | .NET 5 |
| Relational / logical patterns | 9.0 | .NET 5 |
| Target-typed `new` | 9.0 | .NET 5 |
| `global using` | 10.0 | .NET 6 |
| File-scoped namespaces | 10.0 | .NET 6 |
| Record structs | 10.0 | .NET 6 |
| Natural lambda types | 10.0 | .NET 6 |
| Raw string literals | 11.0 | .NET 7 |
| List patterns | 11.0 | .NET 7 |
| `required` members | 11.0 | .NET 7 |
| `file`-scoped types | 11.0 | .NET 7 |
| Generic attributes | 11.0 | .NET 7 |
| Static abstract interface members | 11.0 | .NET 7 |
| Generic math (`INumber<T>`) | 11.0 | .NET 7 |
| Primary constructors (classes) | 12.0 | .NET 8 |
| Collection expressions `[1,2,3]` | 12.0 | .NET 8 |
| `params` collections | 13.0 | .NET 9 |
| `Lock` type | 13.0 | .NET 9 |
| `Task.WhenEach` | 13.0 | .NET 9 |
| Extension members (`extension` blocks) | 14.0 | .NET 10 |
| `field` keyword in properties | 14.0 | .NET 10 |
| Null-conditional assignment `?.=` | 14.0 | .NET 10 |
| Unbound generics in `nameof` | 14.0 | .NET 10 |

---

## Summary — Modern C# Checklist

| Feature | Use For |
|---|---|
| **Pattern matching** | Replace `if/switch` chains with expressive matching |
| **Records** | DTOs, events, value objects — value equality + immutability |
| **`required`** | Enforce property initialization at compile time |
| **Collection expressions** | `[1, 2, 3]` — concise collection creation |
| **Primary constructors** | DI injection in services — less boilerplate |
| **`file` types** | Hide implementation details within a file |
| **`global using`** | Reduce repetitive `using` directives |
| **Raw strings** | JSON, SQL, multi-line text without escaping |
| **`params` spans** | Variable arguments without array allocation |
| **List patterns** | Destructure arrays/lists in `switch` expressions |


Explore modern C# features from C# 7 to 13, including pattern matching, records, collection expressions, and primary constructors for cleaner, more expressive code.

Modern C# Language Features: Pattern Matching, Records, and More


## 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. [Why Task Combinators Matter](#why-task-combinators-matter)
2. [Task.WhenAll](#taskwhenall)
3. [Start First, Await One-by-One](#start-first-await-one-by-one)
4. [Task.WhenAny](#taskwhenany)
5. [Task.WhenEach (.NET 9)](#taskwheneach-net-9)
6. [Parallel.ForEachAsync](#parallelforeachasync)
7. [Exception Handling by Combinator](#exception-handling-by-combinator)
8. [Concurrent Scenario: Prefer task1, Fallback to task2](#concurrent-scenario-prefer-task1-fallback-to-task2)
9. [Decision Guide](#decision-guide)

---

## Why Task Combinators Matter

When an application performs multiple async operations, the hard part is usually not writing the operations themselves. The hard part is orchestration:

- Do you need all results before continuing?
- Do you only need the fastest result?
- Do you want to process results as they complete?
- Do you need bounded parallelism to protect CPU, I/O, or downstream services?

Task combinators solve these orchestration problems with expressive, reliable APIs.

---

## Task.WhenAll

**C# 5.0 / .NET 4.5**

Purpose: Runs multiple tasks concurrently and completes when all of them finish.

- Returns an array of results for `Task<T>` overloads.

```csharp
Task<string> t1 = FetchAsync("url1");
Task<string> t2 = FetchAsync("url2");
Task<string> t3 = FetchAsync("url3");

string[] results = await Task.WhenAll(t1, t2, t3);
```

- [OK] Use for fan-out / scatter-gather patterns.
- [!] If one or more tasks fail, `await Task.WhenAll(...)` throws. Inspect individual tasks if you need full error details.

---

## Start First, Await One-by-One

Another common pattern is to start multiple tasks first, then await them one-by-one:

```csharp
Task task1 = DoTask1();
Task task2 = DoTask2();
Task task3 = DoTask3();

await task1;
await task2;
await task3;
```

This is concurrent in the success path because all tasks are created before the first `await`.

How it differs from `Task.WhenAll`:

- Success case: often similar total time.
- Failure case: stops at the first failed `await`, so later tasks might not be observed in that method.
- `Task.WhenAll`: gives a single coordination point and naturally fits "wait for everything" intent.

If you need all tasks to complete and want consistent exception handling, prefer `Task.WhenAll`:

```csharp
Task task1 = DoTask1();
Task task2 = DoTask2();
Task task3 = DoTask3();

try
{
    await Task.WhenAll(task1, task2, task3);
}
catch
{
    // Inspect all faults if needed.
    var failures = new[] { task1, task2, task3 }
        .Where(t => t.IsFaulted)
        .SelectMany(t => t.Exception!.Flatten().InnerExceptions)
        .ToList();

    throw failures.Count == 1
        ? failures[0]
        : new AggregateException(failures);
}
```

---

## Task.WhenAny

**C# 5.0 / .NET 4.5**

Purpose: Completes when any of the supplied tasks finishes.

- Returns the first completed task.

```csharp
Task<string> fastest = await Task.WhenAny(
    FetchAsync("primary"),
    FetchAsync("fallback"));

string result = await fastest;
```

- [OK] Use for racing, timeouts, or first-response-wins patterns.
- [!] The other tasks keep running unless you cancel them.

---

## Task.WhenEach (.NET 9)

**.NET 9.0 / C# 13.0**

Purpose: Returns an `IAsyncEnumerable<Task<T>>` that yields tasks in completion order.

```csharp
Task<int>[] tasks = [ComputeAsync(1), ComputeAsync(2), ComputeAsync(3)];

await foreach (Task<int> completed in Task.WhenEach(tasks))
{
    int result = await completed;
    Console.WriteLine(result);
}
```

- [OK] Process results as soon as each task finishes, without manual bookkeeping.

---

## Parallel.ForEachAsync

**.NET 6.0**

Purpose: Processes items in parallel with async/await and built-in degree-of-parallelism control.

```csharp
var urls = new[] { "url1", "url2", "url3" };

await Parallel.ForEachAsync(urls,
    new ParallelOptions { MaxDegreeOfParallelism = 3 },
    async (url, ct) =>
    {
        string html = await httpClient.GetStringAsync(url, ct);
        Process(html);
    });
```

- [OK] Preferred over manual `Task.WhenAll` + `Select` when you need bounded parallelism.

---

## Exception Handling by Combinator

Different combinators surface exceptions differently. Use the pattern that matches your intent.

### Task.WhenAll: collect all failures

`await Task.WhenAll(...)` throws if any task fails. To inspect all faults, catch once, then inspect each task.

```csharp
Task<string> t1 = FetchAsync("url1");
Task<string> t2 = FetchAsync("url2");
Task<string> t3 = FetchAsync("url3");

try
{
    string[] results = await Task.WhenAll(t1, t2, t3);
    return results;
}
catch
{
    var failures = new[] { t1, t2, t3 }
        .Where(t => t.IsFaulted)
        .SelectMany(t => t.Exception!.Flatten().InnerExceptions)
        .ToList();

    if (failures.Count == 1)
    {
        throw failures[0];
    }

    throw new AggregateException(failures);
}
```

### Task.WhenAny: winner first, handle loser tasks explicitly

`WhenAny` only tells you which task completed first. The winner can still be faulted/canceled, and losers can fault later.

```csharp
using var cts = new CancellationTokenSource();

Task<string> primary = FetchAsync("primary", cts.Token);
Task<string> fallback = FetchAsync("fallback", cts.Token);

Task<string> winner = await Task.WhenAny(primary, fallback);
Task<string> loser = winner == primary ? fallback : primary;

try
{
    string result = await winner; // May throw if winner faulted/canceled
    cts.Cancel();                 // Stop loser if possible
    return result;
}
catch (Exception winnerEx)
{
    // Winner failed: optionally try loser before failing the request.
    try
    {
        return await loser;
    }
    catch (Exception loserEx)
    {
        throw new AggregateException("Winner and loser both failed.", winnerEx, loserEx);
    }
}
finally
{
    // Observe loser completion to avoid hidden/unobserved failures.
    _ = loser.ContinueWith(_ => { }, TaskScheduler.Default);
}
```

### Task.WhenEach: isolate per-item failures

`WhenEach` is best when each result is independent. Handle each completed task separately so one fault does not stop all processing.

```csharp
Task<int>[] tasks = [ComputeAsync(1), ComputeAsync(2), ComputeAsync(3)];
var failures = new List<Exception>();

await foreach (Task<int> completed in Task.WhenEach(tasks))
{
    try
    {
        int value = await completed;
        Console.WriteLine($"Success: {value}");
    }
    catch (Exception ex)
    {
        failures.Add(ex);
        Console.WriteLine($"Failed: {ex.Message}");
    }
}

if (failures.Count > 0)
{
    throw new AggregateException("One or more computations failed.", failures);
}
```

### Parallel.ForEachAsync: fail-fast by default, aggregate when needed

By default, an unhandled exception in one iteration stops the whole operation. Catch inside the loop if you want best-effort behavior.

```csharp
var urls = new[] { "url1", "url2", "url3" };
var failures = new ConcurrentBag<Exception>();

await Parallel.ForEachAsync(urls,
    new ParallelOptions { MaxDegreeOfParallelism = 3 },
    async (url, ct) =>
    {
        try
        {
            string html = await httpClient.GetStringAsync(url, ct);
            Process(html);
        }
        catch (Exception ex)
        {
            failures.Add(new Exception($"{url} failed", ex));
        }
    });

if (!failures.IsEmpty)
{
    throw new AggregateException(failures);
}
```

---

## Concurrent Scenario: Prefer task1, Fallback to task2

Requirement:

- `task1` and `task2` must start in parallel.
- If `task1` completes with a non-null result, use it.
- If `task1` returns null, use `task2`.

### Simple version

```csharp
Task<string?> task1 = GetPrimaryAsync();
Task<string?> task2 = GetFallbackAsync();

// Both tasks are already running concurrently.
string? primary = await task1;

if (primary is not null)
{
    return primary;
}

return await task2;
```

### Try/Catch Best Practices for This Scenario

- Catch `OperationCanceledException` separately and rethrow with `throw;` when caller cancellation is requested.
- If you catch broad `Exception`, do it only at the orchestration boundary, then inspect task states and rethrow meaningful exceptions.
- Do not use `throw ex;` because it resets the original stack trace.
- Prefer one boundary log entry in the catch block plus final structured failure details when mapping task outcomes.
- Always observe both tasks (for example with `Task.WhenAll`) to avoid hidden or unobserved exceptions.
- Keep business decision logic after the catch section: first choose successful result path, then map fault/cancel outcomes deterministically.

Use this variant when you need deterministic behavior across all outcomes and explicit exception semantics.

---

## Decision Guide

- Use `Task.WhenAll` when all operations are required.
- Use `Task.WhenAny` when the first completed operation is enough.
- Use `Task.WhenEach` when you want streaming completion-order processing.
- Use `Parallel.ForEachAsync` when processing many inputs with bounded concurrency.
- Use the primary/fallback pattern when business logic prefers one source but can accept another.

Task combinators are not just about speed. They are about expressing concurrency intent clearly, which makes code easier to reason about, test, and operate in production.


Learn when to use Task.WhenAll, Task.WhenAny, Task.WhenEach, and Parallel.ForEachAsync, including practical patterns for primary/fallback concurrency in real apps.

C# Task Combinators: Task.WhenAll, Task.WhenAny, Task.WhenEach, and Parallel.ForEachAsync


# C# Configuration & Options Pattern — Cheatsheet

A quick, scannable one-page reference for configuration sources, Options pattern registration, lifetime decisions, and common patterns in ASP.NET Core.

## Configuration Sources (Last Wins)

```
1. appsettings.json
2. appsettings.{Environment}.json  (e.g., appsettings.Development.json)
3. User Secrets (Development only)
4. Environment Variables
5. Command-line arguments
```

## Quick Start — Register & Consume

**Register in Program.cs:**
```csharp
builder.Services.Configure<EmailSettings>(
    builder.Configuration.GetSection("EmailSettings"));
```

**Inject & use:**
```csharp
public class EmailSender
{
    private readonly EmailSettings _settings;
    public EmailSender(IOptions<EmailSettings> options) => _settings = options.Value;
    
    public void Send(string to) { /* use _settings */ }
}
```

## Options Interfaces — Choose Your Lifetime

| Interface | Lifetime | Reloads | Use For |
|---|---|---|---|
| `IOptions<T>` | Singleton | No | Static settings (secrets, connection strings) |
| `IOptionsSnapshot<T>` | Scoped | Per-request | Changing settings in scoped services (feature flags) |
| `IOptionsMonitor<T>` | Singleton | Live + callback | Singletons that react to config changes |

## Named Options — Multiple Configs of Same Type

```csharp
// Register
builder.Services.Configure<BlobStorageSettings>("Images", 
    builder.Configuration.GetSection("Storage:Images"));
builder.Services.Configure<BlobStorageSettings>("Documents", 
    builder.Configuration.GetSection("Storage:Documents"));

// Consume
public class StorageService
{
    public StorageService(IOptionsSnapshot<BlobStorageSettings> options)
    {
        var imageContainer = options.Get("Images").ContainerName;
        var docContainer = options.Get("Documents").ContainerName;
    }
}
```

## Validation — Always Use `.ValidateOnStart()`

```csharp
builder.Services
    .AddOptions<EmailSettings>()
    .BindConfiguration("EmailSettings")
    .ValidateDataAnnotations()
    .ValidateOnStart();  // ← Catches errors at startup, not first request
```

**With data annotations:**
```csharp
public class EmailSettings
{
    [Required]
    public string SmtpHost { get; init; } = string.Empty;
    
    [Range(1, 65535)]
    public int SmtpPort { get; init; } = 587;
    
    [EmailAddress]
    public string FromAddress { get; init; } = string.Empty;
}
```

**Custom inline validation:**
```csharp
builder.Services
    .AddOptions<EmailSettings>()
    .BindConfiguration("EmailSettings")
    .Validate(s => !string.IsNullOrEmpty(s.SmtpHost) && s.SmtpPort is >= 1 and <= 65535, 
              "Invalid SMTP settings")
    .ValidateOnStart();
```

## Environment Variables

Use double underscore (`__`) as section separator:

```bash
export EmailSettings__SmtpHost=smtp.example.com
export EmailSettings__SmtpPort=587
export ConnectionStrings__Default="Server=prod;Database=MyApp"
```

## PostConfigure — Computed Defaults

```csharp
builder.Services.PostConfigure<EmailSettings>(settings =>
{
    if (string.IsNullOrEmpty(settings.FromAddress))
        settings.FromAddress = $"noreply@{settings.SmtpHost}";
});
```

## User Secrets (Development Only)

```bash
# Initialize
dotnet user-secrets init

# Set a secret
dotnet user-secrets set "EmailSettings:ApiKey" "my-secret-key"

# Access via IConfiguration (no code change needed)
var apiKey = configuration["EmailSettings:ApiKey"];
```

## Binding Patterns

**Method 1 — Simple (no validation):**
```csharp
builder.Services.Configure<EmailSettings>(builder.Configuration.GetSection("EmailSettings"));
```

**Method 2 — With validation (recommended):**
```csharp
builder.Services
    .AddOptions<EmailSettings>()
    .BindConfiguration("EmailSettings")
    .ValidateDataAnnotations()
    .ValidateOnStart();
```

**Method 3 — Immediate binding (no DI):**
```csharp
var settings = builder.Configuration.GetSection("EmailSettings").Get<EmailSettings>()!;
```

## IOptionsMonitor with Change Callback

```csharp
public class CacheService : IDisposable
{
    private CacheSettings _settings;
    private readonly IDisposable? _changeListener;

    public CacheService(IOptionsMonitor<CacheSettings> monitor)
    {
        _settings = monitor.CurrentValue;
        _changeListener = monitor.OnChange(newSettings =>
        {
            _settings = newSettings;
            Console.WriteLine($"Cache updated: TTL={_settings.TtlMinutes}m");
        });
    }

    public void Dispose() => _changeListener?.Dispose();
}
```

## Anti-Patterns & Fixes

| Problem | Fix |
|---|---|
| `IConfiguration` everywhere (magic strings) | Use `IOptions<T>` for type safety |
| Secrets in `appsettings.json` | Use User Secrets (dev) or env vars (prod) |
| No validation on options | Use `ValidateDataAnnotations()` + `ValidateOnStart()` |
| `IOptions<T>` in Singleton needing live reload | Use `IOptionsMonitor<T>` |
| `IOptionsSnapshot<T>` in Singleton | **Runtime error** — use `IOptionsMonitor<T>` |

## Quick Checklist

- [ ] Config is in `appsettings.json` with environment overrides
- [ ] Options class created with `public const string SectionName`
- [ ] Registered in Program.cs with `Configure<T>()` or `AddOptions<T>().BindConfiguration()`
- [ ] Validation configured with `ValidateDataAnnotations()` and `ValidateOnStart()`
- [ ] Secrets stored in User Secrets (dev) or env vars (prod)
- [ ] Correct interface chosen: `IOptions<T>`, `IOptionsSnapshot<T>`, or `IOptionsMonitor<T>`
- [ ] `PostConfigure<T>()` used for computed defaults if needed

---

**See the full guide:** [C# Configuration & Options Pattern](csharp-configuration-options-pattern.md)


One-page quick reference for ASP.NET Core configuration, Options pattern, and DI registration patterns.

C# Configuration & Options Pattern - Cheatsheet


## Table of Contents

1. [Quick Answer](#quick-answer)
2. [What ConfigureAwait(false) Actually Changes](#what-configureawaitfalse-actually-changes)
3. [Why Deadlocks Happen with .Result and .Wait()](#why-deadlocks-happen-with-result-and-wait)
4. [3-Tier ASP.NET Core API Example](#3-tier-aspnet-core-api-example)
5. [Why ASP.NET Core Usually Does Not Need ConfigureAwait(false)](#why-aspnet-core-usually-does-not-need-configureawaitfalse)
6. [Where ConfigureAwait(false) Still Matters](#where-configureawaitfalse-still-matters)
7. [When NOT to Use ConfigureAwait(false)](#when-not-to-use-configureawaitfalse)
8. [.NET 8: ConfigureAwaitOptions](#net-8-configureawaitoptions)
9. [Blocking vs await: Complete Comparison](#blocking-vs-await-complete-comparison)
10. [Practical Rules You Can Apply Today](#practical-rules-you-can-apply-today)

---

## Quick Answer

- `ConfigureAwait(false)` tells `await` to not capture the current `SynchronizationContext`.
- Continuations resume on any available thread pool thread.
- In ASP.NET Core, there is no request `SynchronizationContext`, so `ConfigureAwait(false)` is usually a functional no-op in app code.
- In reusable library code, still use it consistently because callers might be WPF, WinForms, or older ASP.NET Framework.

---

## What ConfigureAwait(false) Actually Changes

Default `await` behavior is equivalent to `ConfigureAwait(true)`.

```csharp
async Task<string> GetDataAsync(string url)
{
    using var client = new HttpClient();

    // Do not capture caller context
    string data = await client.GetStringAsync(url).ConfigureAwait(false);
    return data;
}
```

Without `ConfigureAwait(false)`:

1. Capture current `SynchronizationContext` (if one exists).
2. Suspend method and return thread to caller.
3. When task finishes, continuation posts back to captured context.

With `ConfigureAwait(false)`:

1. Do not capture `SynchronizationContext`.
2. Suspend method and return thread to caller.
3. Continuation runs on whatever thread is available.

---

## Why Deadlocks Happen with .Result and .Wait()

Classic deadlock pattern in UI apps:

```csharp
// Library method without ConfigureAwait(false)
public async Task<string> FetchAsync(string url)
{
    using var client = new HttpClient();
    return await client.GetStringAsync(url);
}

// UI thread caller (WPF/WinForms)
public string LoadSynchronously()
{
    // Blocks UI thread
    return FetchAsync("https://example.com").Result;
}
```

What goes wrong:

- `.Result` blocks the UI thread.
- `await` continuation tries to return to UI context.
- UI thread is blocked and cannot run continuation.
- Both sides wait forever.

Adding `ConfigureAwait(false)` inside the async method can break that cycle because continuation no longer depends on UI context.

```csharp
public async Task<string> FetchAsync(string url)
{
    using var client = new HttpClient();
    return await client.GetStringAsync(url).ConfigureAwait(false);
}
```

Important: this does not make `.Result` a good pattern. The right fix is still to use `await` end-to-end.

---

## 3-Tier ASP.NET Core API Example

Let us use a simple API with Controller -> Service -> Repository.

### Repository

```csharp
public interface IWeatherRepository
{
    Task<string> GetRawForecastAsync(CancellationToken ct);
}

public sealed class WeatherRepository : IWeatherRepository
{
    private readonly HttpClient _http;

    public WeatherRepository(HttpClient http)
    {
        _http = http;
    }

    public async Task<string> GetRawForecastAsync(CancellationToken ct)
    {
        // In ASP.NET Core app code, ConfigureAwait(false) is optional.
        return await _http.GetStringAsync("https://example.com/forecast", ct);
    }
}
```

### Service

```csharp
public interface IWeatherService
{
    Task<WeatherDto> GetForecastAsync(CancellationToken ct);
}

public sealed class WeatherService : IWeatherService
{
    private readonly IWeatherRepository _repo;

    public WeatherService(IWeatherRepository repo)
    {
        _repo = repo;
    }

    public async Task<WeatherDto> GetForecastAsync(CancellationToken ct)
    {
        string raw = await _repo.GetRawForecastAsync(ct);
        return new WeatherDto
        {
            Summary = raw,
            RetrievedAtUtc = DateTime.UtcNow
        };
    }
}

public sealed class WeatherDto
{
    public string Summary { get; set; } = string.Empty;
    public DateTime RetrievedAtUtc { get; set; }
}
```

### Controller

```csharp
[ApiController]
[Route("api/weather")]
public sealed class WeatherController : ControllerBase
{
    private readonly IWeatherService _service;

    public WeatherController(IWeatherService service)
    {
        _service = service;
    }

    [HttpGet]
    public async Task<ActionResult<WeatherDto>> Get(CancellationToken ct)
    {
        WeatherDto dto = await _service.GetForecastAsync(ct);
        return Ok(dto);
    }
}
```

### Registration (Program.cs)

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddHttpClient<IWeatherRepository, WeatherRepository>();
builder.Services.AddScoped<IWeatherService, WeatherService>();

var app = builder.Build();
app.MapControllers();
app.Run();
```

This works perfectly without `ConfigureAwait(false)` in app layers because ASP.NET Core does not install a request `SynchronizationContext`.

---

## Why ASP.NET Core Usually Does Not Need ConfigureAwait(false)

ASP.NET Core behavior:

- `SynchronizationContext.Current` is usually `null`.
- `await` continuations already run on thread pool threads.
- There is no old request-thread affinity like ASP.NET Framework.

So in Controller/Service/Repository inside ASP.NET Core app code, adding `ConfigureAwait(false)` usually does not change runtime behavior.

Still, teams sometimes keep it in app code for consistency with shared libraries. That is a style choice, not a requirement.

---

## Where ConfigureAwait(false) Still Matters

It matters most in reusable libraries.

```csharp
public sealed class ExternalApiClient
{
    private readonly HttpClient _http;

    public ExternalApiClient(HttpClient http)
    {
        _http = http;
    }

    // Library code: always avoid capturing caller context
    public async Task<string> FetchDataAsync(string url, CancellationToken ct)
    {
        using var response = await _http.GetAsync(url, ct).ConfigureAwait(false);
        response.EnsureSuccessStatusCode();

        string content = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
        return content;
    }
}
```

Why this is safer:

- Library cannot assume caller environment.
- Caller may be WPF, WinForms, Xamarin, or legacy ASP.NET Framework.
- Avoids context capture overhead and reduces deadlock risk for bad sync callers.

---

## When NOT to Use ConfigureAwait(false)

Do not use it when continuation must run on a context-bound thread.

Examples:

1. WPF/WinForms event handlers that update UI controls after `await`.
2. Code paths that depend on context-specific state in older frameworks.

```csharp
// WPF/WinForms example
private async void BtnLoad_Click(object sender, EventArgs e)
{
    string text = await _client.FetchDataAsync("https://example.com", CancellationToken.None);
    // Resume on UI context so control access is safe.
    txtOutput.Text = text;
}
```

If you write UI app code, default `await` is typically the correct behavior in event handlers.

---

## .NET 8: ConfigureAwaitOptions

In .NET 8+, you can use flags-based options.

```csharp
// Equivalent intent to ConfigureAwait(false)
await task.ConfigureAwait(ConfigureAwaitOptions.None);

// Guarantee asynchronous continuation
await task.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
```

Common options:

- `None`: do not capture context.
- `ContinueOnCapturedContext`: capture and resume on context.
- `ForceYielding`: force asynchronous continuation.
- `SuppressThrowing`: advanced scenario, avoid automatic exception rethrow.

For most code, simple `ConfigureAwait(false)` remains easy to read and widely understood.

---

## Blocking vs await: Complete Comparison

| Approach                        | Blocks Thread? | Deadlock Risk with SyncContext? | Scales Under Load? | Recommendation                    |
| ------------------------------- | -------------- | ------------------------------- | ------------------ | --------------------------------- |
| `await task`                    | No             | No                              | Yes                | Always prefer                     |
| `task.Result`                   | Yes            | Yes                             | No                 | Avoid                             |
| `task.Wait()`                   | Yes            | Yes                             | No                 | Avoid                             |
| `task.GetAwaiter().GetResult()` | Yes            | Yes                             | No                 | Only last-resort bootstrap/legacy |

Even in ASP.NET Core where deadlock risk is lower, blocking still burns worker threads and hurts throughput.

---

## Practical Rules You Can Apply Today

1. Prefer async all the way: avoid sync-over-async wrappers.
2. In ASP.NET Core app layers, `ConfigureAwait(false)` is optional.
3. In reusable library/NuGet code, apply `ConfigureAwait(false)` on every await.
4. In UI event handlers, do not use `ConfigureAwait(false)` if you must update controls after await.
5. If legacy code must block, use `.GetAwaiter().GetResult()` rather than `.Result`, and keep that boundary as small as possible.

If you remember one line: use `await` everywhere you can, and use `ConfigureAwait(false)` where your code should not care about the caller's context.


Learn exactly what ConfigureAwait(false) does, when it prevents deadlocks, why ASP.NET Core usually does not need it, and how to apply it correctly in reusable library code.

ConfigureAwait(false) in C# and ASP.NET Core: Deadlocks, 3-Tier API, and Library Rules

Master SynchronizationContext, understand how .Result and .Wait() cause deadlocks in WPF/WinForms/ASP.NET Framework, and why ASP.NET Core eliminated this problem entirely.

C# Deadlocks and SynchronizationContext — Why ASP.NET Core Doesn't Have It


# C# Configuration & Options Pattern

Configuration is core to building maintainable ASP.NET Core apps. This post walks through the built-in layered configuration model, the Options pattern for strongly-typed settings, the differences between `IOptions<T>`, `IOptionsSnapshot<T>` and `IOptionsMonitor<T>`, named options, validation, and common anti-patterns.

## Configuration in ASP.NET Core

- ASP.NET Core uses a layered configuration system: multiple sources are combined and later sources override earlier ones.
- Default configuration sources (last wins):

```
1. appsettings.json
2. appsettings.{Environment}.json  (e.g., appsettings.Development.json)
3. User Secrets                     (Development only)
4. Environment Variables
5. Command-line arguments
```

- `appsettings.json` is the primary, file-based config store:

```json
{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=MyApp;Trusted_Connection=true"
  },
  "Logging": { "LogLevel": { "Default": "Information" } },
  "EmailSettings": {
    "SmtpHost": "smtp.example.com",
    "SmtpPort": 587,
    "FromAddress": "noreply@example.com",
    "EnableSsl": true
  },
  "FeatureFlags": { "EnableNewCheckout": false, "MaxRetries": 3 }
}
```

- You can access configuration directly via `IConfiguration` but that is error-prone (magic strings, no type-safety). Prefer the Options pattern.

```csharp
// IConfiguration - raw access (not recommended for most scenarios)
var smtpHost = builder.Configuration["EmailSettings:SmtpHost"];
var port = builder.Configuration.GetValue<int>("EmailSettings:SmtpPort");
var connStr = builder.Configuration.GetConnectionString("Default");
```

#### Sample appsetting
Assume the following setup: `appsettings.json` is used for all environments, and `appsettings.dev.json` is used when the `ASPNETCORE_ENVIRONMENT` is set to `dev`.
appsettings.json
```
  "MyApp": {
    "ApiKey": "my-key-12345"
  }
```

appsettings.dev.json
```
  "MyApp": {
    "ApiKey": "my-key-10000"
  }
```


appsettings.prd.json
```
// No ApiKey for MyApp in this file
```


Now, if you run `dotnet run`, you'll see different values depending on the environment:

- If you run with `ASPNETCORE_ENVIRONMENT=dev`, you'll get `my-key-10000` for **ApiKey**.
- If you run with `ASPNETCORE_ENVIRONMENT=prd`, the config will return `my-key-12345`.


#### Use user-secrets
You can use `user-secrets` to override config values from appsettings. User secrets allow you to store sensitive values on your local development machine, so you don't need to check credentials into the repo. For development or production, you can inject these values into the application from a Vault or environment variables.


```
dotnet user-secrets init
dotnet user-secrets set "MyApp:ApiKey" "99999"
dotnet user-secrets list
```


#### A few other commands for `user-secrets`
```
# Remove a secret
dotnet user-secrets remove "MyApp:ApiKey"

# Clear all secrets
dotnet user-secrets clear
```


#### Use Environment Variables
Running the following PowerShell command will override both appsettings and user-secrets:
```
# Set and run in one command (PowerShell)
$env:MyApp__ApiKey="secret"; dotnet run
```


#### Use command-line arguments
Command-line arguments will override all other configuration sources:
```
dotnet run --MyApp:ApiKey="command-line-key-12345"
```


## The Options Pattern (`IOptions<T>`)

- The Options pattern binds configuration sections to strongly-typed classes. This gives type-safety, validation, and easier testing.

```csharp
public class EmailSettings
{
    public const string SectionName = "EmailSettings";
    public string SmtpHost { get; init; } = string.Empty;
    public int SmtpPort { get; init; } = 587;
    public string FromAddress { get; init; } = string.Empty;
    public bool EnableSsl { get; init; } = true;
}

// Register in Program.cs
builder.Services.Configure<EmailSettings>(
    builder.Configuration.GetSection(EmailSettings.SectionName));

// Consume via DI
public class EmailSender
{
    private readonly EmailSettings _settings;
    public EmailSender(IOptions<EmailSettings> options) => _settings = options.Value;

    public async Task SendAsync(string to, string body, CancellationToken ct)
    {
        using var client = new SmtpClient(_settings.SmtpHost, _settings.SmtpPort);
        client.EnableSsl = _settings.EnableSsl;
        await client.SendMailAsync(new MailMessage(_settings.FromAddress, to, "Subject", body), ct);
    }
}
```

## `IOptions<T>` vs `IOptionsSnapshot<T>` vs `IOptionsMonitor<T>`

| Interface             |  Lifetime | Reloads on Change | Use Case                                                      |
| --------------------- | --------: | ----------------: | ------------------------------------------------------------- |
| `IOptions<T>`         | Singleton |                No | Settings that never change at runtime                         |
| `IOptionsSnapshot<T>` |    Scoped | Yes (per-request) | Settings that may change and are consumed in scoped services  |
| `IOptionsMonitor<T>`  | Singleton |        Yes (live) | Singleton services that need live reload and change callbacks |

- `IOptions<T>`: read once at startup — simplest and fastest. Use for secrets or values that won't change during runtime.

- `IOptionsSnapshot<T>`: refreshed per request/scope. Useful for feature flags or settings you may update and expect to take effect on the next request. Cannot be injected into Singleton services.

- `IOptionsMonitor<T>`: supports live reload and `OnChange` callbacks. Use when a Singleton needs to react to config changes.

```csharp
// Example: IOptionsMonitor with change callback
public class CacheService : IDisposable
{
    private CacheSettings _settings;
    private readonly IDisposable? _changeListener;

    public CacheService(IOptionsMonitor<CacheSettings> monitor)
    {
        _settings = monitor.CurrentValue;
        _changeListener = monitor.OnChange(newSettings =>
        {
            _settings = newSettings;
            Console.WriteLine($"Cache updated: TTL={newSettings.TtlMinutes}m");
        });
    }

    public void Dispose() => _changeListener?.Dispose();
}
```

## Named Options — multiple configurations of the same type

When you need multiple instances of the same settings class with different values (e.g., two blob containers), use named options:

```json
{
  "Storage": {
    "Images": { "ConnectionString": "...", "ContainerName": "images" },
    "Documents": { "ConnectionString": "...", "ContainerName": "documents" }
  }
}
```

```csharp
public class BlobStorageSettings { public string ConnectionString { get; init; } = string.Empty; public string ContainerName { get; init; } = string.Empty; }

builder.Services.Configure<BlobStorageSettings>("Images", builder.Configuration.GetSection("Storage:Images"));
builder.Services.Configure<BlobStorageSettings>("Documents", builder.Configuration.GetSection("Storage:Documents"));

public class StorageService
{
    private readonly IOptionsSnapshot<BlobStorageSettings> _options;
    public StorageService(IOptionsSnapshot<BlobStorageSettings> options) => _options = options;

    public string GetImageContainer() => _options.Get("Images").ContainerName;
    public string GetDocumentContainer() => _options.Get("Documents").ContainerName;
}
```

## Options Validation

Always validate options to catch misconfiguration early. You can use data annotations, inline validation, or implement `IValidateOptions<T>`.

```csharp
public class EmailSettings
{
    [Required]
    public string SmtpHost { get; init; } = string.Empty;

    [Range(1, 65535)]
    public int SmtpPort { get; init; } = 587;

    [Required, EmailAddress]
    public string FromAddress { get; init; } = string.Empty;
}

builder.Services
    .AddOptions<EmailSettings>()
    .BindConfiguration(EmailSettings.SectionName)
    .ValidateDataAnnotations()
    .ValidateOnStart();
```

Inline validation example:

```csharp
builder.Services
  .AddOptions<EmailSettings>()
  .BindConfiguration("EmailSettings")
  .Validate(settings => !string.IsNullOrWhiteSpace(settings.SmtpHost) && settings.SmtpPort is >=1 and <=65535, "EmailSettings validation failed")
  .ValidateOnStart();
```

Or implement reusable validation via `IValidateOptions<T>` for complex checks.

Note: `.ValidateOnStart()` is recommended so the app fails fast on invalid config, that way can detect the error earlier.
For example: if you app configured kafka credential, you asked devOps to setup the value but by some reason the value if misconfigured, would you still want to app to running and fail the API calls? or not let it start-up after the deployment?

## PostConfigure

Use `PostConfigure<T>` to compute defaults or derived values after binding, use this when want fallback logic for a config.
```csharp
builder.Services.PostConfigure<EmailSettings>(settings =>
{
    if (string.IsNullOrEmpty(settings.FromAddress))
        settings.FromAddress = $"noreply@{settings.SmtpHost}";
});
```

## Configuration Sources Quick Tips

- User Secrets: development-only secure storage for secrets outside source control (`dotnet user-secrets`).
- Environment variables: preferred in production (use `__` double-underscore to separate sections).
- Command-line args: useful for short-lived overrides during startup.

## Common Anti-Patterns

| Anti-Pattern                                  | Problem                             | Fix                                               |
| --------------------------------------------- | ----------------------------------- | ------------------------------------------------- |
| `IConfiguration` everywhere                   | Magic strings, no type safety       | Use `IOptions<T>`                                 |
| Secrets in `appsettings.json`                 | Committed to source control         | Use User Secrets (dev) or env vars (prod)         |
| No validation on options                      | Bad config causes runtime errors    | `ValidateDataAnnotations()` + `ValidateOnStart()` |
| `IOptions<T>` in Singleton that needs reloads | Values never update                 | Use `IOptionsMonitor<T>`                          |
| `IOptionsSnapshot<T>` in Singleton            | Runtime error (Scoped in Singleton) | Use `IOptionsMonitor<T>`                          |

## Binding Patterns

- `Configure<T>`: common, simple registration.
- `AddOptions<T>().BindConfiguration(...)` — supports validation and `ValidateOnStart()`.
- `Get<T>()` on `IConfigurationSection` — immediate binding (no DI).

## Summary — Configuration Checklist

| Topic                 | Key Takeaway                                                               |
| --------------------- | -------------------------------------------------------------------------- |
| Configuration sources | `appsettings.json` → env JSON → User Secrets → env vars → CLI              |
| Options pattern       | Bind config to strong types for safety and testability                     |
| `IOptions<T>`         | Singleton, read once — for static settings                                 |
| `IOptionsSnapshot<T>` | Scoped, refreshed per request — for changing settings in scoped services   |
| `IOptionsMonitor<T>`  | Singleton, live reload + `OnChange` — for singletons that react to updates |
| Named options         | Use when you need multiple configurations of same type                     |
| Validation            | Use data annotations or `IValidateOptions<T>` and `ValidateOnStart()`      |
| Secrets               | Don't store in source control — use User Secrets (dev) or env vars (prod)  |

---


Practical guide to configuration in ASP.NET Core using the Options pattern, validation, named options and reload strategies.

C# Configuration & Options Pattern

Master dependency injection in ASP.NET Core with a complete guide to transient, scoped, and singleton lifetimes, captive dependencies, and real-world 3-layer architecture patterns.

C# Dependency Injection & Service Lifetimes


## Table of Contents

1. [Introduction](#introduction)
2. [Define Enum with Power of Two](#define-enum-with-power-of-two)
3. [Define Enum with Bit Shift](#define-enum-with-bit-shift)
4. [Using the Enum Flags](#using-the-enum-flags)
5. [Conclusion](#conclusion)

## Introduction

A quick code snippet to show how to use enum flags by using the power of two. You
can define your enum and set the values as follows. This will make the
combined flag values unique.

## Define Enum with Power of Two

```
public enum MyType : uint {
		Undefined = 0,
		Type1 = 1,
		Type2 = 2,
		Type3 = 4,
		Type4 = 8,
		Type5 = 16
	}
```

## Define Enum with Bit Shift

Or you can use the bit shift if you don't want to count the numbers.

```
public enum MyType2 : uint {
		Undefined = 0,
		Type1 = 1,
		Type2 = 2 << 0,
		Type3 = 2 << 1,
		Type4 = 2 << 2,
		Type5 = 2 << 3
	}
```

## Using the Enum Flags

Following are a few ways to use this enum.

```
// set value
		var myvalue = MyType.Type1 | MyType.Type2;
		Console.WriteLine(myvalue);

		var myvalue2 = MyType2.Type1 | MyType2.Type2;
		Console.WriteLine(myvalue2);

		// check value
		if ((myvalue2 & MyType2.Type1) == MyType2.Type1) {
			Console.WriteLine("myvalue2 has Type1");
		}

		// check value
		if ((myvalue2 & MyType2.Type4) != MyType2.Type4) {
			Console.WriteLine("myvalue2 doesn't have type4");
		}
```

The above code result will be the following:

3
3
myvalue2 has Type1
myvalue2 doesn't have type4
myvalue2 has type4? False

## Conclusion

Using the `[Flags]` attribute and the power of two for enum values allows you to combine multiple enum values into a single variable and check for specific flags using bitwise operations.


A quick code snippet showing how to use C# enum flags with the power of two for defining combinable flag values.

csharp

Subscribe for Updates