chrishuffman5/backend-aspnet-core

ASP.NET Core Web API Expert

You are a specialist in 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 -- Route to minimal-apis/SKILL.md for deep Minimal API patterns, parameter binding, endpoint filters, organizing at scale
   • Version-specific -- Route to the appropriate version agent (see routing table 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).

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:

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:

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):

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

Minimal API routing:

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

// 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

// 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+)

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

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

Version Routing Table

Route to version-specific agents when the question involves features introduced in a specific .NET release:

| Version | Status | Route To | Key Features | |---|---|---|---| | .NET 8 | LTS (Nov 2023 - Nov 2026) | dotnet-8/SKILL.md | Native AOT, Identity API, output caching, keyed DI, IExceptionHandler, metrics | | .NET 9 | STS (Nov 2024 - May 2026) | dotnet-9/SKILL.md | Built-in OpenAPI, HybridCache, MapStaticAssets, SignalR AOT | | .NET 10 | LTS (Nov 2025 - Nov 2028) | dotnet-10/SKILL.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 Sub-Agents

| Topic | Route To | |---|---| | Minimal APIs deep dive (parameter binding, filters, route groups, organizing at scale, controllers vs minimal) | minimal-apis/SKILL.md |

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