dotnet-aspnet

name

dotnet-aspnet

description

Applies ASP.NET Core best practices for building Web and REST APIs. Use when creating controllers, minimal APIs, configuring middleware, routing, model binding, validation, authentication, authorization, error handling with ProblemDetails, OpenAPI/Swagger, health checks, CORS, rate limiting, or structuring an ASP.NET Core project. For DI, Options pattern, and configuration that apply to any .NET host, use dotnet-fundamentals.

ASP.NET Core Web API Best Practices

When to Use

• Creating new controllers, minimal API endpoints, or feature folders in an ASP.NET Core project
• Configuring the middleware pipeline, routing, or model binding
• Adding authentication, authorization policies, or [Authorize]-based access control
• Implementing error handling with ProblemDetails (RFC 9457) or IExceptionHandler
• Wiring up OpenAPI/Swagger, health checks, CORS, rate limiting, output caching, or response compression
• Reviewing or restructuring an existing ASP.NET Core project to align with best practices

This skill covers the HTTP / web layer only. For dependency injection, Options pattern, and configuration that apply to any .NET host, see dotnet-fundamentals.

Core Principles

• Use feature folders, not layer folders. Keep Program.cs lean — extract registrations into extension methods.
• Always use [ApiController] on MVC controllers; prefer TypedResults in minimal APIs.
• Accept CancellationToken on every async endpoint.
• Map domain exceptions to ProblemDetails — never leak internal exception messages.
• Middleware order matters: exception handler → status code pages → HSTS/HTTPS → CORS → auth → rate limiter → endpoints.

Reference Index

Detailed patterns and code samples live in references/:

• project-and-endpoints.md — Project structure, Controllers vs Minimal APIs, routing, API conventions, response types (TypedResults, [ProducesResponseType])
• model-binding-validation.md — Binding sources ([FromBody], [FromRoute], etc.), Data Annotations, FluentValidation, ValidationProblemDetails
• middleware.md — Pipeline order, custom middleware with primary constructors
• auth.md — JWT Bearer, authorization policies, IAuthorizationHandler, RequireAuthorization
• error-handling.md — ProblemDetails, IExceptionHandler (.NET 8+), UseStatusCodePages
• openapi-and-cross-cutting.md — OpenAPI/Swagger, XML doc generation, health checks (liveness/readiness), CORS, rate limiting, output caching, response compression

Related Skills

• dotnet-fundamentals — Foundation: DI, Options pattern, configuration, modern C# idioms used by every endpoint and service in this skill
• dotnet-ef-core — Data access with Entity Framework Core
• dotnet-tester — Unit and integration testing for endpoints
• dotnet-xmldocs — XML documentation comments (feed OpenAPI)
• dotnet-nuget-manager — Invoked for adding health-check, resilience, and middleware packages
• dotnet-sdk-builder — Generates typed HTTP clients for consuming these APIs
• dotnet-reviewer — Reviews ASP.NET Core code for security, performance, and architecture issues