---

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
• ASP.NET Core Middleware
• ASP.NET Core Best Practices
• Configuration in ASP.NET Core
• Authentication and Authorization

References

• patterns.md - Detailed middleware patterns, security patterns, configuration patterns, DI patterns, error handling patterns, and logging patterns
• 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(quot;appsettings.{builder.Environment.EnvironmentName}.json", optional: true)
    .AddEnvironmentVariables()
    .AddUserSecrets<Program>(optional: true);

Security Patterns

Authentication Setup

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!))
        };
    });

Authorization Policies

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AdminOnly", policy =>
        policy.RequireRole("Admin"));
    options.AddPolicy("MinAge18", policy =>
        policy.RequireClaim("Age", "18", "19", "20")); // simplified
});

Anti-Patterns to Avoid

Anti-Pattern	Why It's Bad	Better Approach
new HttpClient()	Socket exhaustion	IHttpClientFactory
Sync-over-async (Task.Result)	Thread pool starvation	await properly
Storing secrets in appsettings.json	Security risk	User Secrets, Key Vault
Catching all exceptions silently	Hides bugs	Use IExceptionHandler
async void in middleware	Crashes process	async Task
Missing HTTPS redirect	Security risk	UseHttpsRedirection()

Performance Best Practices

1. Use async/await everywhere — avoid sync blocking calls
2. Pool DbContext properly — use scoped lifetime
3. Enable response compression — UseResponseCompression()
4. Use output caching — UseOutputCache() for .NET 7+
5. Profile with diagnostic tools — Visual Studio Diagnostic Tools, PerfView
6. Avoid allocations in hot paths — use Span<T>, pooling

Deliver

• production-credible ASP.NET Core code and config
• a clear request pipeline and hosting story
• verification that matches the affected endpoints and middleware
• security headers and HTTPS configured correctly

Validate

• middleware order is intentional and documented
• security and configuration changes are explicit
• endpoint behavior is covered by tests or smoke checks
• no blocking calls in async context
• secrets are not committed to source control
• health checks are implemented for production readiness