.NET API copilot-instructions.md Template

Description

## copilot-instructions.md for .NET API Projects

This is a .NET 9 API project with C# 13. Follow these conventions:

### Architecture
- Minimal API style with endpoint grouping via `MapGroup`
- Vertical slice architecture: each feature folder contains endpoint, handler, request, response
- Project structure: `Features/`, `Data/`, `Middleware/`, `Extensions/`
- Shared concerns in `Common/`: base types, validation, pagination

### Endpoints
- Group related endpoints: `app.MapGroup("/api/v1/users").WithTags("Users")`
- Use typed request/response records
- Return `IResult` types: `Results.Ok(data)`, `Results.Created($"/api/v1/users/{id}", data)`
- Add OpenAPI metadata: `.WithName()`, `.WithSummary()`, `.Produces<T>()`
- Filter/validation via endpoint filters: `.AddEndpointFilter<ValidationFilter<T>>()`

### Data Access (EF Core 9)
- `DbContext` with `DbSet<T>` for each entity
- Fluent API configuration in `IEntityTypeConfiguration<T>` classes
- Repository pattern only if abstracting is justified; otherwise use DbContext directly
- `AsNoTracking()` for read-only queries
- Global query filters for soft delete: `.HasQueryFilter(e => !e.IsDeleted)`
- Migrations: `dotnet ef migrations add YYYYMMDD_Description`

### DTOs and Mapping
- Request records: `public record CreateUserRequest(string Name, string Email);`
- Response records: `public record UserResponse(Guid Id, string Name, string Email);`
- Use Mapster or manual mapping extension methods: `entity.ToResponse()`
- Never expose entity models in API responses

### Validation
- FluentValidation validators per request type
- Register validators via `AddValidatorsFromAssemblyContaining<Program>()`
- Endpoint filter applies validation automatically before handler executes
- Return 422 Unprocessable Entity with field-level error details

### Authentication
- JWT Bearer authentication with `AddAuthentication().AddJwtBearer()`
- Short-lived access tokens (15 min) and refresh tokens (30 days)
- Authorization policies: `.RequireAuthorization("AdminOnly")`
- Claims-based authorization for fine-grained access control

### Error Handling
- Global exception middleware returning `ProblemDetails` (RFC 7807)
- Custom exceptions: `NotFoundException`, `ConflictException`, `ForbiddenException`
- Structured logging with Serilog: `Log.Information("User {UserId} created", userId)`

### Performance
- Response caching: `OutputCache` for read-heavy endpoints
- Use `IAsyncEnumerable<T>` for streaming large result sets
- Background tasks with `IHostedService` for async processing
- Health checks: `MapHealthChecks("/health")`

Free to copy and use. Compatible with GitHub Copilot, GPT-5.

Usage Instructions

Tags

Compatible AI Models

Version History

Related Prompts