/aspnet-core

name: aspnet-core
description: "Build, debug, modernize, or review ASP.NET Core applications with correct hosting, middleware, security, configuration, logging, and deployment patterns on current .NET. USE FOR: working on ASP.NET Core apps, services, or middleware; changing auth, routing, configuration, hosting, or deployment behavior; deciding between ASP.NET Core sub-stacks. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Requires an ASP.NET Core project or solution."

ASP.NET Core

Trigger On

• working on ASP.NET Core apps, services, or middleware
• changing auth, routing, configuration, hosting, or deployment behavior
• deciding between ASP.NET Core sub-stacks such as Blazor, Minimal APIs, or controller APIs
• debugging request pipeline issues
• modernizing legacy ASP.NET to ASP.NET Core

Documentation

• [ASP.NET Core Overview](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-10.0)
• [ASP.NET Core Middleware](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/middleware/?view=aspnetcore-10.0)
• [ASP.NET Core Best Practices](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/best-practices?view=aspnetcore-10.0)
• [Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-10.0)
• [Authentication and Authorization](https://learn.microsoft.com/en-us/aspnet/core/security/?view=aspnetcore-10.0)

References

• [patterns.md](references/patterns.md) - Detailed middleware patterns, security patterns, configuration patterns, DI patterns, error handling patterns, and logging patterns
• [anti-patterns.md](references/anti-patterns.md) - Common ASP.NET Core mistakes including HttpClient misuse, async anti-patterns, configuration errors, DI issues, middleware ordering problems, and security vulnerabilities

Workflow

1. **Detect the real hosting shape first:**

• top-level `Program.cs` structure
• middleware order and registration
• auth model (Identity, JWT, OAuth, cookies)
• endpoint registrations and routing

2. **Follow the correct middleware order:**

   ExceptionHandler → HttpsRedirection → Static Files → Routing
   → CORS → Authentication → Authorization → Rate Limiting
   → Response Caching → Custom Middleware → Endpoints

3. **Use built-in patterns correctly:**

• Prefer `IOptions<T>` / `IOptionsSnapshot<T>` for configuration
• Use `ILogger<T>` for structured logging
• Use `IHttpClientFactory` for HTTP clients (never `new HttpClient()`)
• Use `IHostedService` / `BackgroundService` for background work

4. **Route specialized work to specific skills:**

• UI and components → `blazor`
• Real-time → `signalr`
• RPC → `grpc`
• New HTTP APIs → `minimal-apis` (prefer unless controllers needed)
• Controller APIs → `web-api`

5. **Validate with build, tests, and targeted endpoint checks.**

Current Upstream Notes

• ASP.NET Core `v10.0.11` is a servicing release rather than a new programming model. It updates OpenAPI to `2.7.5`, fixes restoration of expired client-persisted Blazor circuit state, and refreshes servicing dependencies. Keep the existing middleware and endpoint architecture, then rerun focused OpenAPI, interactive-rendering, auth, and startup tests.
• The August 2026 Microsoft Learn overview for `aspnetcore-10.0` remains the routing entry point for choosing between Blazor, Minimal APIs, controller APIs, SignalR, and gRPC; the refresh does not justify changing an existing app model by itself.

Middleware Patterns

Correct Order Matters

var app = builder.Build();

app.UseExceptionHandler("/error");      // 1. Catch all exceptions
app.UseHsts();                          // 2. Security headers
app.UseHttpsRedirection();              // 3. HTTPS redirect
app.UseStaticFiles();                   // 4. Serve static files
app.UseRouting();                       // 5. Route matching
app.UseCors();                          // 6. CORS policy
app.UseAuthentication();                // 7. Who are you?
app.UseAuthorization();                 // 8. Can you access?
app.UseRateLimiter();                   // 9. Rate limiting
app.UseResponseCaching();               // 10. Response cache
app.MapControllers();                   // 11. Endpoints

Custom Middleware Pattern

public class RequestTimingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<RequestTimingMiddleware> _logger;

    public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var sw = Stopwatch.StartNew();
        await _next(context);
        _logger.LogInformation("Request {Path} completed in {Elapsed}ms",
            context.Request.Path, sw.ElapsedMilliseconds);
    }
}

Configuration Patterns

Strongly-Typed Options

// appsettings.json
{
  "EmailSettings": {
    "SmtpServer": "smtp.example.com",
    "Port": 587
  }
}

// Registration
builder.Services.Configure<EmailSettings>(
    builder.Configuration.GetSection("EmailSettings"));

// Usage
public class EmailService(IOptions<EmailSettings> options)
{
    private readonly EmailSettings _settings = options.Value;
}

Environment-Based Configuration

builder.Configuration
    .AddJsonFile("appsettings.json", optional: false)
    .AddJsonFile($"appsettings.{builder.Environment.EnvironmentName}.json", optional: true)
    .AddEnvironmentVariables()
    .AddUserSecrets<Program>(optional: true);

Security Patterns

Authentication Setup

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>