.NET 10 & C# 14 Best Practices

.NET 10 (LTS, Nov 2025) with C# 14. Covers minimal APIs, not MVC.

Official docs: .NET 10 | C# 14 | ASP.NET Core 10

Detail Files

File	Topics
csharp-14.md	Extension blocks, field keyword, null-conditional assignment
minimal-apis.md	Validation, TypedResults, filters, modular monolith, vertical slices
security.md	JWT auth, CORS, rate limiting, OpenAPI security, middleware order
infrastructure.md	Options, resilience, channels, health checks, caching, Serilog, EF Core, keyed services
testing.md	WebApplicationFactory, integration tests, auth testing
anti-patterns.md	HttpClient, DI captive, blocking async, N+1 queries
libraries.md	MediatR, FluentValidation, Mapster, ErrorOr, Polly, Aspire

---

Quick Start

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>14</LangVersion>
    <Nullable>enable</Nullable>
  </PropertyGroup>
</Project>
```text

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

// Core services
builder.Services.AddValidation();
builder.Services.AddProblemDetails();
builder.Services.AddOpenApi();

// Security
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
builder.Services.AddRateLimiter(opts => { /* see security.md */ });

// Infrastructure
builder.Services.AddHealthChecks();
builder.Services.AddOutputCache();

// Modules
builder.Services.AddUsersModule();

var app = builder.Build();

// Middleware (ORDER MATTERS - see security.md)
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseCors();
app.UseRateLimiter();
app.UseAuthentication();
app.UseAuthorization();
app.UseOutputCache();

app.MapOpenApi();
app.MapHealthChecks("/health");
app.MapUsersEndpoints();
app.Run();
```text

---

## Decision Flowcharts

### Result vs Exception

```dot
digraph {
    "Error type?" [shape=diamond];
    "Expected?" [shape=diamond];
    "Result<T>/ErrorOr" [shape=box];
    "Exception" [shape=box];
    "Error type?" -> "Expected?" [label="domain"];
    "Error type?" -> "Exception" [label="infrastructure"];
    "Expected?" -> "Result<T>/ErrorOr" [label="yes"];
    "Expected?" -> "Exception" [label="no"];
}
```text

### IOptions Selection

```dot
digraph {
    "Runtime changes?" [shape=diamond];
    "Per-request?" [shape=diamond];
    "IOptions<T>" [shape=box];
    "IOptionsSnapshot<T>" [shape=box];
    "IOptionsMonitor<T>" [shape=box];
    "Runtime changes?" -> "IOptions<T>" [label="no"];
    "Runtime changes?" -> "Per-request?" [label="yes"];
    "Per-request?" -> "IOptionsSnapshot<T>" [label="yes"];
    "Per-request?" -> "IOptionsMonitor<T>" [label="no"];
}
```text

### Channel Type

```dot
digraph {
    "Trust producer?" [shape=diamond];
    "Can drop?" [shape=diamond];
    "Bounded+Wait" [shape=box,style=filled,fillcolor=lightgreen];
    "Bounded+Drop" [shape=box];
    "Unbounded" [shape=box];
    "Trust producer?" -> "Unbounded" [label="yes"];
    "Trust producer?" -> "Can drop?" [label="no"];
    "Can drop?" -> "Bounded+Drop" [label="yes"];
    "Can drop?" -> "Bounded+Wait" [label="no"];
}
```text

---

## Key Patterns Summary

### C# 14 Extension Blocks

```csharp
extension<T>(IEnumerable<T> source)
{
    public bool IsEmpty => !source.Any();
}
```text

### .NET 10 Built-in Validation

```csharp
builder.Services.AddValidation();
app.MapPost("/users", (UserDto dto) => TypedResults.Ok(dto));
```text

### TypedResults (Always Use)

```csharp
app.MapGet("/users/{id}", async (int id, IUserService svc) =>
    await svc.GetAsync(id) is { } user
        ? TypedResults.Ok(user)
        : TypedResults.NotFound());
```text

### Module Pattern

```csharp
public static class UsersModule
{
    public static IServiceCollection AddUsersModule(this IServiceCollection s) => s
        .AddScoped<IUserService, UserService>();

    public static IEndpointRouteBuilder MapUsersEndpoints(this IEndpointRouteBuilder app)
    {
        var g = app.MapGroup("/api/users").WithTags("Users");
        g.MapGet("/{id}", GetUser.Handle);
        return app;
    }
}
```text

### HTTP Resilience

```csharp
builder.Services.AddHttpClient<IApi, ApiClient>()
    .AddStandardResilienceHandler();
```text

### Error Handling (RFC 9457)

```csharp
builder.Services.AddProblemDetails();
app.UseExceptionHandler();
app.UseStatusCodePages();
```text

---

## MANDATORY Patterns (Always Use These)

| Task                | ✅ ALWAYS Use                    | ❌ NEVER Use                         |
| ------------------- | -------------------------------- | ------------------------------------ |
| Extension members   | C# 14 `extension<T>()` blocks    | Traditional `this` extension methods |
| Property validation | C# 14 `field` keyword            | Manual backing fields                |
| Null assignment     | `obj?.Prop = value`              | `if (obj != null) obj.Prop = value`  |
| API returns         | `TypedResults.Ok()`              | `Results.Ok()`                       |
| Options validation  | `.ValidateOnStart()`             | Missing validation                   |
| HTTP resilience     | `AddStandardResilienceHandler()` | Manual Polly configuration           |
| Timestamps          | `DateTime.UtcNow`                | `DateTime.Now`                       |

---

## Quick Reference Card

```text
┌─────────────────────────────────────────────────────────────────┐
│                    .NET 10 / C# 14 PATTERNS                      │
├─────────────────────────────────────────────────────────────────┤
│ EXTENSION PROPERTY:  extension<T>(IEnumerable<T> s) {           │
│                        public bool IsEmpty => !s.Any();         │
│                      }                                          │
├─────────────────────────────────────────────────────────────────┤
│ FIELD KEYWORD:       public string Name {                       │
│                        get => field;                            │
│                        set => field = value?.Trim();            │
│                      }                                          │
├─────────────────────────────────────────────────────────────────┤
│ OPTIONS VALIDATION:  .BindConfiguration(Section)                │
│                      .ValidateDataAnnotations()                 │
│                      .ValidateOnStart();   // CRITICAL!         │
├─────────────────────────────────────────────────────────────────┤
│ HTTP RESILIENCE:     .AddStandardResilienceHandler();           │
├─────────────────────────────────────────────────────────────────┤
│ TYPED RESULTS:       TypedResults.Ok(data)                      │
│                      TypedResults.NotFound()                    │
│                      TypedResults.Created(uri, data)            │
├─────────────────────────────────────────────────────────────────┤
│ ERROR PATTERN:       ErrorOr<User> or user?.Match(...)          │
├─────────────────────────────────────────────────────────────────┤
│ IOPTIONS:            IOptions<T>        → startup, no reload    │
│                      IOptionsSnapshot<T> → per-request reload   │
│                      IOptionsMonitor<T>  → live + OnChange()    │
└─────────────────────────────────────────────────────────────────┘
```text

---

## Anti-Patterns Quick Reference

| Anti-Pattern                 | Fix                                         |
| ---------------------------- | ------------------------------------------- |
| `new HttpClient()`           | Inject `HttpClient` or `IHttpClientFactory` |
| `Results.Ok()`               | `TypedResults.Ok()`                         |
| Manual Polly config          | `AddStandardResilienceHandler()`            |
| Singleton → Scoped           | Use `IServiceScopeFactory`                  |
| `GetAsync().Result`          | `await GetAsync()`                          |
| Exceptions for flow          | Use `ErrorOr<T>` Result pattern             |
| `DateTime.Now`               | `DateTime.UtcNow`                           |
| Missing `.ValidateOnStart()` | Always add to Options registration          |

See [anti-patterns.md](anti-patterns.md) for complete list.

---



## Code Navigation (Serena MCP)

**Primary approach:** Use Serena symbol operations for efficient code navigation:

1. **Find definitions**: `serena_find_symbol` instead of text search
2. **Understand structure**: `serena_get_symbols_overview` for file organization
3. **Track references**: `serena_find_referencing_symbols` for impact analysis
4. **Precise edits**: `serena_replace_symbol_body` for clean modifications

**When to use Serena vs traditional tools:**
- ✅ **Use Serena**: Navigation, refactoring, dependency analysis, precise edits
- ✅ **Use Read/Grep**: Reading full files, pattern matching, simple text operations
- ✅ **Fallback**: If Serena unavailable, traditional tools work fine

**Example workflow:**
```text
# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"

# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"
```
## Libraries Quick Reference

| Library          | Package                                          | Purpose        |
| ---------------- | ------------------------------------------------ | -------------- |
| MediatR          | `MediatR`                                        | CQRS           |
| FluentValidation | `FluentValidation.DependencyInjectionExtensions` | Validation     |
| Mapster          | `Mapster.DependencyInjection`                    | Mapping        |
| ErrorOr          | `ErrorOr`                                        | Result pattern |
| Polly            | `Microsoft.Extensions.Http.Resilience`           | Resilience     |
| Serilog          | `Serilog.AspNetCore`                             | Logging        |

See [libraries.md](libraries.md) for usage examples.