Aspnet Core

---
name: aspnet-core
description: "Expert skill for ASP.NET Core Web API across .NET 8, 9, and 10. Covers middleware pipeline, dependency injection, Kestrel, routing, controllers vs Minimal APIs, model binding, filters, configuration, error handling, and deployment. WHEN: \"ASP.NET Core\", \"ASP.NET\", \".NET Web API\", \"Kestrel\", \"Minimal API\", \"controller API\", \"[ApiController]\", \"MapGet\", \"MapPost\", \"middleware pipeline\", \"UseRouting\", \"UseAuthorization\", \"ProblemDetails\", \"IExceptionHandler\", \"output caching\", \"SignalR\", \"Blazor Web App\", \"WebApplication.CreateBuilder\". For deep Minimal API patterns (parameter binding, endpoint filters, organizing at scale), use the `aspnet-minimal-apis` skill instead."
license: MIT
---

# ASP.NET Core Web API

This skill covers ASP.NET Core Web API development across .NET 8 LTS, .NET 9 STS, and .NET 10 LTS. ASP.NET Core is a cross-platform, high-performance web framework built on the .NET runtime. It uses Kestrel as its web server, a middleware pipeline for request processing, and built-in dependency injection as a first-class citizen.

## How to Approach Tasks

1. **Classify** the request:
   - **Architecture** -- Load `references/architecture.md` for middleware pipeline internals, DI container, Kestrel, routing engine, filter pipeline, hosting models
   - **Best practices** -- Load `references/best-practices.md` for configuration patterns, security hardening, performance tuning, testing, deployment
   - **Troubleshooting** -- Load `references/diagnostics.md` for common errors, middleware ordering issues, DI resolution failures, performance profiling
   - **Minimal APIs** -- Use the `aspnet-minimal-apis` skill for deep Minimal API patterns, parameter binding, endpoint filters, organizing at scale
   - **Version-specific** -- Read the matching version reference (see Version-specific guidance below)

2. **Identify version** -- Determine the target .NET version from the project's `<TargetFramework>` (net8.0, net9.0, net10.0), `global.json`, or explicit mention. Default to .NET 10 for new projects.

3. **Load context** -- Read the relevant reference file before answering.

4. **Analyze** -- Apply ASP.NET Core-specific reasoning. Consider middleware order, DI lifetimes, Kestrel configuration, and the controller vs Minimal API trade-off.

5. **Recommend** -- Provide concrete C# code examples with explanations. Always qualify trade-offs.

6. **Verify** -- Suggest validation steps: `dotnet build`, `dotnet test`, checking middleware order, DI scope validation.

## Core Architecture

### Request Pipeline

Every HTTP request flows through a linear chain of middleware components. Each component receives `HttpContext`, optionally calls `next()`, and can act on both the request (inbound) and response (outbound).

```csharp
var app = builder.Build();

app.UseExceptionHandler("/error");     // 1. Must be FIRST
app.UseHsts();                          // 2. Strict-Transport-Security
app.UseHttpsRedirection();              // 3. Before auth
app.UseStaticFiles();                   // 4. Before routing (no auth overhead)
app.UseRouting();                       // 5. Before CORS, Auth, Endpoints
app.UseCors("MyPolicy");               // 6. After routing, before auth
app.UseAuthentication();                // 7. Identify user
app.UseAuthorization();                 // 8. Check permissions
app.MapControllers();                   // 9. Endpoints
```

**Critical ordering rules:**
- `UseExceptionHandler` first -- catches all downstream exceptions
- `UseStaticFiles` before `UseRouting` -- avoids routing overhead for static content
- `UseRouting` before `UseCors` -- CORS needs the matched endpoint
- `UseCors` before `UseAuthentication` -- preflight OPTIONS must not require auth
- `UseAuthentication` before `UseAuthorization` -- identity before permissions

### Dependency Injection

Built-in DI container (`Microsoft.Extensions.DependencyInjection`) with three lifetimes:

```csharp
services.AddTransient<IEmailSender, SmtpEmailSender>();   // New instance every request
services.AddScoped<IOrderRepo, EfOrderRepo>();             // One per HTTP request
services.AddSingleton<IMemoryCache, MemoryCache>();        // One for app lifetime
```

**Captive dependency trap:** Never inject Scoped/Transient into Singleton -- the short-lived service gets captured for the app's lifetime. Enable scope validation:

```csharp
builder.Host.UseDefaultServiceProvider(options =>
{
    options.ValidateScopes = true;
    options.ValidateOnBuild = true;
});
```

### Kestrel Server

Cross-platform, high-performance web server. Always the "inner" server behind a reverse proxy in production:

```
Client -> [Reverse Proxy: Nginx/IIS/YARP] -> [Kestrel] -> ASP.NET Core Pipeline
```

Supports HTTP/1.1, HTTP/2 (default with TLS), and HTTP/3 (QUIC, .NET 7+).

### Routing

Endpoint routing decouples route matching (`UseRouting`) from execution. Middleware between routing and endpoints can inspect `HttpContext.GetEndpoint()` metadata.

**Attribute routing (controllers):**
```csharp
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    [HttpGet("{id:int}")]
    public async Task<IActionResult> GetById(int id) => Ok();
}
```

**Minimal API routing:**
```csharp
var orders = app.MapGroup("/api/orders").RequireAuthorization();
orders.MapGet("/{id:int}", (int id, IOrderService svc) =>
    svc.GetById(id) is Order o ? Results.Ok(o) : Results.NotFound());
```

## Controllers vs Minimal APIs

| Dimension | Controllers | Minimal APIs |
|---|---|---|
| **Performance** | Slightly higher overhead | Faster startup and throughput |
| **Organization** | Natural grouping per class | Route groups + extension methods |
| **Filter pipeline** | Full MVC filters (auth, resource, action, exception, result) | Endpoint filters only (lighter) |
| **Validation** | Auto via `[ApiController]` | Manual (.NET 6-9); auto in .NET 10 |
| **AOT support** | Not supported | Full (with RDG) |
| **OpenAPI** | Attributes + ApiExplorer | Built-in `AddOpenApi()` (.NET 9+) |

**Use Controllers when:** OData, JsonPatch, complex model binding, large teams with MVC experience.
**Use Minimal APIs when:** New projects, microservices, performance-critical, Native AOT required.

Both coexist in the same app -- migrate incrementally.

## Key Patterns

### Error Handling with ProblemDetails

```csharp
// Register ProblemDetails service
builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions["traceId"] =
            Activity.Current?.Id ?? ctx.HttpContext.TraceIdentifier;
    };
});

// IExceptionHandler (.NET 8+) -- structured exception handling
public class GlobalExceptionHandler : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext, Exception exception, CancellationToken ct)
    {
        httpContext.Response.StatusCode = 500;
        await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Title = "Internal Server Error",
            Status = 500
        }, ct);
        return true;
    }
}

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
app.UseExceptionHandler(_ => { });
```

### Configuration with Options Pattern

```csharp
// Bind configuration section to strongly-typed options
builder.Services.AddOptions<OrderServiceOptions>()
    .Bind(builder.Configuration.GetSection("OrderService"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

// IOptions<T>      -- Singleton, reads once at startup
// IOptionsSnapshot  -- Scoped, re-reads per request
// IOptionsMonitor   -- Singleton, reflects changes via OnChange callback
```

### Model Binding

Controllers use `[FromBody]`, `[FromQuery]`, `[FromRoute]`, `[FromHeader]`, `[FromForm]`, `[FromServices]`. The `[ApiController]` attribute enables automatic inference and 400 responses on invalid model state.

Minimal APIs infer binding sources automatically: route template parameters from route, simple types from query string, complex types from body JSON, registered services from DI.

### Filters (Controller Pipeline)

```
Request ->
  [Authorization Filters]
  [Resource Filters - Before]
    [Model Binding]
  [Action Filters - Before]
    [Action Method]
  [Action Filters - After]
  [Result Filters - Before/After]
<- Response
  [Exception Filters]
```

### Keyed DI Services (.NET 8+)

```csharp
builder.Services.AddKeyedSingleton<ICache, MemoryCache>("memory");
builder.Services.AddKeyedSingleton<ICache, RedisCache>("redis");

app.MapGet("/data", ([FromKeyedServices("redis")] ICache cache) =>
    cache.Get("key"));
```

## Version-specific guidance

Read the matching reference when the question involves features introduced in a specific .NET release:

| Version | Status | Reference | What's version-specific |
|---|---|---|---|
| .NET 8 | LTS (Nov 2023 - Nov 2026) | `references/versions/dotnet-8.md` | Native AOT, Identity API, output caching, keyed DI, IExceptionHandler, metrics |
| .NET 9 | STS (Nov 2024 - May 2026) | `references/versions/dotnet-9.md` | Built-in OpenAPI, HybridCache, MapStaticAssets, SignalR AOT |
| .NET 10 | LTS (Nov 2025 - Nov 2028) | `references/versions/dotnet-10.md` | OpenAPI 3.1, built-in validation, SSE TypedResults, Aspire 13, .NET 8 migration |

**Enterprise migration path:** .NET 8 LTS -> .NET 10 LTS (skip .NET 9 STS).

## Feature Skills

| Topic | Skill |
|---|---|
| Minimal APIs deep dive (parameter binding, filters, route groups, organizing at scale, controllers vs minimal) | `aspnet-minimal-apis` |

## Hosting Models

| Model | Server | Use Case |
|---|---|---|
| In-process (IIS) | IISHttpServer | Windows/IIS, highest throughput |
| Out-of-process (IIS) | Kestrel behind IIS | Process isolation |
| Self-hosted | Kestrel behind Nginx/YARP | Linux, containers |
| Docker | Kestrel | Cloud-native, Kubernetes |

**Docker default port changed to 8080 in .NET 8** (non-root). Use `ASPNETCORE_HTTP_PORTS=8080`.

## Cross-Version Feature Matrix

| Feature | .NET 8 | .NET 9 | .NET 10 |
|---|---|---|---|
| Minimal APIs + Route Groups | Yes | Yes | Yes |
| Keyed DI | Yes | Yes | Yes |
| Native AOT (Minimal APIs) | Partial | Partial | Expanded |
| Built-in OpenAPI | No | Yes (3.0) | Yes (3.1 + YAML) |
| Built-in Validation (Minimal) | No | No | Yes |
| HybridCache | No | Preview | Stable |
| IExceptionHandler | Yes | Yes | Yes |
| Server-Sent Events | No | No | Yes |
| HTTP/3 | Stable | Stable | Stable |

## Reference Files

Load these for deep knowledge on specific topics:

- `references/architecture.md` -- Middleware pipeline internals, DI container patterns, Kestrel configuration, routing engine, filter pipeline, hosting models. **Load when:** architecture questions, middleware ordering, DI lifetime issues, Kestrel tuning, reverse proxy setup.
- `references/best-practices.md` -- Configuration patterns, security hardening, performance tuning, testing strategies, deployment patterns. **Load when:** "how should I configure", security review, performance optimization, CI/CD setup.
- `references/diagnostics.md` -- Common errors and fixes, middleware ordering bugs, DI resolution failures, authentication debugging, performance profiling. **Load when:** troubleshooting errors, debugging auth issues, diagnosing performance problems.

## Diagnostic Scripts

Ready-made dotnet CLI audit (read-only) in `scripts/`.

- `scripts/01-project-audit.sh` -- Target frameworks, vulnerable/deprecated/outdated packages, build health