ASP.NET Core & MVC

#MVC and choosing an application model

A controller that queries SQL, calculates discounts and constructs HTML is hard to change and test. MVC separates coordination, business behavior and rendering.

// IProductService and ProductViewModel are application types.
public sealed class ProductsController(IProductService products) : Controller
{
    public async Task<IActionResult> Details(int id, CancellationToken ct)
    {
        var product = await products.GetAsync(id, ct);       // (1)
        if (product is null) return NotFound();
        return View(product);                              // (2)
    }
}

Choose according to team needs, UI and conventions. Minimal APIs need not live entirely in Program.cs, and MVC is not a complete application architecture.

#Kestrel, IIS and reverse proxies

The application needs an HTTP server; public hosting also requires TLS, routing and limit decisions. Kestrel is a cross-platform server that can run at the edge or behind a proxy such as Nginx or YARP.

Client -> optional CDN/WAF -> reverse proxy -> Kestrel -> pipeline

IIS in-process:     IIS -> ASP.NET Core Module -> IIS HTTP Server -> app
IIS out-of-process: IIS -> ASP.NET Core Module -> Kestrel -> app

using Microsoft.AspNetCore.HttpOverrides;
using System.Net;

// Before Build; replace this address with the trusted proxy's address.
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor
        | ForwardedHeaders.XForwardedProto;                // (1)
    options.KnownProxies.Add(IPAddress.Parse("10.0.0.10")); // (2)
});
// Early in the pipeline, before HTTPS redirection:
app.UseForwardedHeaders();                                 // (3)

IIS in-process hosting does not use Kestrel to receive requests. A reverse proxy helps centralize TLS and load balancing but is not mandatory for a correctly configured Kestrel deployment. Align body limits and timeouts across layers.

#Pipeline order, custom middleware, Use, Run and Map

Middleware can run before and after next or short-circuit the pipeline. Ordering creates nesting: responses unwind in reverse order, and an exception handler can catch downstream failures only.

Forwarded headers -> exception handler -> HSTS/HTTPS -> static files
  -> routing -> CORS -> authentication -> rate limiter -> authorization
  -> endpoint -> response unwinds through executed middleware

Use: may call next; Run(RequestDelegate): terminal handler
Map("/path", branch): branch pipeline
MapGet / MapControllers: register endpoints, not the same branching API

public sealed class RequestLogMiddleware(RequestDelegate next)
{
    public async Task InvokeAsync(HttpContext context,
        ILogger<RequestLogMiddleware> log)
    {
        var started = Stopwatch.GetTimestamp();             // (1)
        try { await next(context); }                        // (2)
        finally
        {
            double ms = Stopwatch.GetElapsedTime(started).TotalMilliseconds;
            log.LogInformation("Request {TraceId} ended after {ElapsedMs} ms",
                context.TraceIdentifier, ms);               // (3)
        }
    }
}

// Required CORS, authentication, authorization and limiter services are registered.
app.UseExceptionHandler();
app.UseMiddleware<RequestLogMiddleware>();
if (!app.Environment.IsDevelopment()) app.UseHsts();
app.UseHttpsRedirection();
app.UseRouting();
app.UseCors("storefront");
app.UseAuthentication();
app.UseRateLimiter();                                       // (4)
app.UseAuthorization();
app.MapControllers();

Conventional middleware constructors are long-lived; inject scoped services into InvokeAsync or use suitably registered IMiddleware. Parameterless app.Run() starts the host; Run(handler) is terminal middleware. Static files served before authorization are public; protect private content through an appropriate path.

#Routing and binding: destination and input sources

Routing selects an endpoint; binding converts request values into parameters. An int route constraint restricts matching rather than validating user input with a field error.

// Conventional routing for controllers with views:
app.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");

// Attribute routing; IOrderService and UpdateOrder are application types.
[ApiController]
[Route("api/orders")]
public sealed class OrdersController(IOrderService orders) : ControllerBase
{
    [HttpPut("{id:int}")]
    public async Task<IActionResult> Update(
        [FromRoute] int id,                              // (1)
        [FromQuery] bool notify,
        [FromHeader(Name = "Idempotency-Key")] string? key,
        [FromBody] UpdateOrder request,                  // (2)
        CancellationToken ct)
    {
        await orders.UpdateAsync(id, request, notify, key, ct);
        return NoContent();
    }
}

// Minimal API grouping:
var group = app.MapGroup("/api/products").RequireAuthorization();
group.MapGet("/{id:int}", (int id) => TypedResults.Ok(new { Id = id }));

ApiController infers sources from types, routes and DI registration; explicit attributes help when the source matters. Minimal APIs have their own rules, including TryParse and BindAsync, rather than MVC model binders. /orders/abc does not match {id:int}, commonly producing 404; conversion failure after a match may produce 400. Constraints do not replace range checks.

#Validation, filters and .NET 10 Minimal APIs

Binding asks whether input can be read, validation whether its shape is acceptable, and the domain whether the operation is currently allowed. Stock availability needs enforcement with a safe update, not merely a request annotation.

// .NET 10 Web project; package: Microsoft.Extensions.Validation.
using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddValidation();                         // (1)
var app = builder.Build();
app.MapPost("/products", (CreateProduct request) =>
    TypedResults.Created("/products/1", request));         // (2) illustrative id
app.Run();

public sealed class CreateProduct
{
    [Required, StringLength(200)]
    public string Name { get; set; } = "";
    [Range(0.01, 1_000_000)]
    public decimal Price { get; set; }
}

Action filters see bound arguments; resource filters run before binding. Exception filters do not cover all middleware or response-writing failures. Middleware usually suits HTTP-wide logging or global errors. See the validation reference for metadata discovery across assemblies.

#Results, status codes and response contracts

An HTTP response includes status and headers as well as JSON. Use return types that reveal success and failure possibilities rather than returning 200 for every outcome.

using Microsoft.AspNetCore.Http.HttpResults;

// IOrderReader and OrderDto are application types registered with DI.
app.MapGet("/orders/{id:int}",
    async Task<Results<Ok<OrderDto>, NotFound>>
    (int id, IOrderReader reader, CancellationToken ct) =>
    {
        var order = await reader.GetAsync(id, ct);          // (1)
        return order is null
            ? TypedResults.NotFound()
            : TypedResults.Ok(order);                      // (2)
    });

IActionResult supports varied MVC results; ActionResult<T> adds a success type. Document failure responses too, and avoid serializing EF entities directly.

202 does not claim completion. A 401 generally challenges with WWW-Authenticate according to the scheme; 403 forbids. Define a consistent business-error policy instead of memorizing a status for every exception type.

#DI lifetimes, captive dependencies and keyed services

DI handles ownership and lifetime as well as construction. A long-lived service retaining a short-lived dependency can accidentally share state across requests.

// Application types: IPaymentProvider, CardProvider and WalletProvider.
builder.Services.AddKeyedScoped<IPaymentProvider, CardProvider>("card");
builder.Services.AddKeyedScoped<IPaymentProvider, WalletProvider>("wallet"); // (1)

app.MapPost("/payments/card",
    ([FromKeyedServices("card")] IPaymentProvider provider) =>
        TypedResults.Ok(provider.Name));                   // (2)

// A singleton's unit of work, not a singleton-held DbContext:
await using var scope = scopeFactory.CreateAsyncScope();   // (3)
var work = scope.ServiceProvider.GetRequiredService<IOrderWork>();
await work.ExecuteAsync(ct);

A singleton retaining a scoped DbContext is a captive dependency. ValidateScopes detects many violations when enabled; exercise startup validation in tests too. A captured transient can effectively live as long as its singleton owner. Let the container dispose what it owns; avoid arbitrary disposal of injected services or calling BuildServiceProvider inside registrations.

#Configuration, options, environments and secrets

Deployment differences should not produce scattered settings or committed passwords. Bind typed options and fail early when required values are invalid.

Default application configuration, low -> high priority:
appsettings.json -> appsettings.{Environment}.json
  -> User Secrets in Development -> environment variables -> command-line

Later added providers can override earlier values.
Payments__ApiKey maps to Payments:ApiKey.

public sealed class PaymentOptions
{
    [Required] public string ApiKey { get; set; } = "";
    [Range(1, 60)] public int TimeoutSeconds { get; set; } = 10;
}

// Before Build; DataAnnotations attributes need their namespace.
builder.Services.AddOptions<PaymentOptions>()
    .BindConfiguration("Payments")                          // (1)
    .ValidateDataAnnotations()
    .ValidateOnStart();                                     // (2)

Development, Staging and Production select settings and debugging behavior, not a security boundary. With WebApplicationBuilder, DOTNET_ENVIRONMENT takes precedence if ASPNETCORE_ENVIRONMENT is also set; avoid conflicting values. Development User Secrets stay outside Git but are not an encrypted vault. Use an appropriate production secret store or injection mechanism; environment variables are not encryption.

#IExceptionHandler, ProblemDetails and structured logging

Repeated action-level try/catch creates inconsistent errors and can expose stack traces. Represent expected outcomes as results and centralize unexpected failures with a trace identifier linking the response to internal logs.

using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;

// Before Build:
builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalErrors>();       // (1)
// After Build, early: app.UseExceptionHandler();

public sealed class GlobalErrors(ILogger<GlobalErrors> log) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(HttpContext context,
        Exception exception, CancellationToken ct)
    {
        log.LogError(exception, "Unhandled request {TraceId}",
            context.TraceIdentifier);                     // (2)
        context.Response.StatusCode = 500;
        await context.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Status = 500,
            Title = "An unexpected error occurred.",
            Extensions = { ["traceId"] = context.TraceIdentifier }
        }, contentType: "application/problem+json", cancellationToken: ct); // (3)
        return true;                                      // (4)
    }
}

Once a response starts, rewriting its status or body may be impossible. Treat request cancellation according to its expected semantics. In .NET 10, default diagnostics for exceptions handled with true are suppressed by default; deliberately log what is needed without duplication. Levels are Trace, Debug, Information, Warning, Error and Critical. Exclude tokens and card data. See the error-handling reference.

#CORS, preflight, rate limits and health checks

A browser needs permission to read cross-origin responses; an API also needs traffic limits and readiness signals. These are distinct concerns, none replacing authentication.

using System.Threading.RateLimiting;
using Microsoft.AspNetCore.Diagnostics.HealthChecks;

builder.Services.AddCors(o => o.AddPolicy("storefront", p => p
    .WithOrigins("https://shop.example.com")
    .WithMethods("GET", "POST")
    .WithHeaders("Content-Type", "Authorization")));       // (1)
builder.Services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.AddFixedWindowLimiter("browse", p =>
    {
        p.PermitLimit = 100;
        p.Window = TimeSpan.FromMinutes(1);
        p.QueueLimit = 0;
    });                                                    // (2)
});
builder.Services.AddHealthChecks();                        // (3)

// After Build; install CORS and rate-limiting middleware as shown earlier.
app.MapGet("/catalog", () => TypedResults.Ok("Catalog"))
    .RequireRateLimiting("browse");
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false                                 // (4)
});
app.MapHealthChecks("/health/ready");

CORS is a browser policy and does not restrict curl or prevent CSRF. For credentialed cookie requests, use AllowCredentials with explicit origins rather than a wildcard. In-process limiting is neither a distributed quota nor complete DDoS protection; enforce shared limits at a gateway where needed. Avoid restart loops from dependency-based liveness and keep detailed health output private.

#HttpClient and resilience: time budgets and retries

Creating a new client and handler for every call loses connection reuse and can exhaust sockets. The factory separates client and handler lifetimes and centralizes configuration and resilience.

// Package: Microsoft.Extensions.Http.Resilience.
using Microsoft.Extensions.Http.Resilience;

builder.Services.AddHttpClient<CatalogClient>(http =>
{
    http.BaseAddress = new Uri("https://catalog.example.com/"); // (1)
}).AddStandardResilienceHandler(options =>
{
    options.Retry.DisableForUnsafeHttpMethods();             // (2)
});

public sealed class CatalogClient(HttpClient http)
{
    public Task<ProductDto?> GetAsync(int id, CancellationToken ct) =>
        http.GetFromJsonAsync<ProductDto>($"products/{id}", ct); // (3)
}

A long-lived client with SocketsHttpHandler and PooledConnectionLifetime is also valid. Avoid capturing a short-lived typed client in a singleton without reviewing DNS and lifetime behavior. Tune total budgets, per-attempt timeouts and retries to the dependency. Retrying a payment may duplicate an operation that succeeded before its response was lost.

#BackgroundService, durable jobs and deployment

Cleanup or reconciliation should not be fire-and-forget work tied to a request scope. Use an in-process loop for repeatable work and a durable scheduler or queue when losing work on restart is unacceptable.

// IOrderMaintenance is a scoped application service.
public sealed class OrderCleaner(IServiceScopeFactory scopes,
    ILogger<OrderCleaner> log) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromMinutes(10)); // (1)
        try
        {
            while (await timer.WaitForNextTickAsync(stoppingToken))
            {
                try
                {
                    await using var scope = scopes.CreateAsyncScope(); // (2)
                    var work = scope.ServiceProvider
                        .GetRequiredService<IOrderMaintenance>();
                    await work.CleanAsync(stoppingToken);
                }
                catch (Exception ex) when (ex is not OperationCanceledException)
                {
                    log.LogError(ex, "Order cleanup failed");        // (3)
                }
            }
        }
        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
        {
            // Normal shutdown.
        }
    }
}
// Register before Build:
// builder.Services.AddHostedService<OrderCleaner>();

Unhandled ExecuteAsync exceptions stop the host by default from .NET 6. In .NET 10 all of ExecuteAsync runs in the background; do not use its pre-await portion as a startup barrier. Hangfire offers persisted jobs, retries and a dashboard. Quartz specializes in scheduling, with persistence and clustering when configured. Neither guarantees exactly-once side effects; design idempotent jobs.

1. Publish Release as framework-dependent or self-contained and promote a tested, fixed artifact.
2. Use SDK images for container builds and ASP.NET runtime images for execution; patch both runtime and OS.
3. Inject configuration and secrets per environment and configure trusted proxies and TLS.
4. Run schema migrations as a controlled step with backward-compatible changes for rolling or blue-green deployments.
5. Gate traffic on readiness and support graceful shutdown and request draining; deployment strategy alone does not guarantee zero downtime.