aspnet-core

REQUIRED BACKGROUND: You MUST also follow the core clean-code and backend-fundamentals skills. This skill adds ASP.NET Core-specific patterns on top.

aspnet-core

Layer contract (matches structure.tree)

Layer	May import	Never
*Endpoints.cs / controllers	the feature service, DTOs	repositories, other endpoints
*Service.cs	repositories, other services	HttpContext, IHttpContextAccessor, transport types
Repositories/	the DbContext / DB client	services, endpoints
Common/ (middleware/filters)	services (for auth lookups)	repositories

Services stay transport-free — no HttpContext — so they are unit-testable and a transport swap (minimal API → controllers → gRPC) is an endpoint-layer-only change.

DI & wiring

• Register every service in Program.cs (AddScoped/AddSingleton/AddTransient); resolve by constructor or endpoint-parameter injection — never new a service.
• Program.cs owns wiring only, not business logic. One WebApplication, middleware pipeline registered once, feature endpoints mapped via <Feature>Endpoints.Map(app).
• Lifetimes: Scoped for per-request (the default for services touching the DB), Singleton only for stateless/thread-safe helpers, Transient for cheap stateless objects. A captive dependency (Singleton holding a Scoped) is a bug.
• Keep Program reachable to tests (public partial class Program;) so WebApplicationFactory<Program> can build the app without binding a port.

Endpoints (thin)

• A handler binds/validates the DTO → calls ONE service method → returns the value (the host serializes). Do not build the response envelope by hand.
• No try/catch for error shaping in an endpoint — throw a typed exception and let the global middleware shape it.
• Flow CancellationToken from the handler into every downstream call.

Validation

• Every body/route/query input is a validated DTO (DataAnnotations or FluentValidation); reject fail-closed before the service runs. The service receives a typed, validated value and never reads the raw request.