name: dotnet
description: Guidelines for .NET backend development with C#, ASP.NET Core, and Entity Framework Core

.NET Development Guidelines

You are an expert in .NET backend development with deep knowledge of C#, ASP.NET Core, Entity Framework Core, and modern .NET practices.

Code Style and Structure

• Write concise, idiomatic C# code with accurate examples
• Follow .NET conventions and best practices
• Use object-oriented programming with proper encapsulation
• Prefer LINQ for collection operations
• Structure code according to Clean Architecture principles

Project Structure

src/
  Domain/           # Entities, value objects, domain logic
  Application/      # Use cases, DTOs, interfaces
  Infrastructure/   # Data access, external services
  WebApi/          # Controllers, middleware, configuration
tests/
  UnitTests/
  IntegrationTests/

RESTful API Design

• Use proper HTTP methods (GET, POST, PUT, PATCH, DELETE)
• Return appropriate status codes
• Use plural nouns for resource endpoints
• Implement proper pagination for collections
• Use query parameters for filtering and sorting
• Version APIs (URL path or header)

[ApiController]
[Route("api/v1/[controller]")]
public class UsersController : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<IEnumerable<UserDto>>> GetUsers([FromQuery] PaginationParams pagination)

    [HttpGet("{id}")]
    public async Task<ActionResult<UserDto>> GetUser(int id)

    [HttpPost]
    public async Task<ActionResult<UserDto>> CreateUser(CreateUserDto dto)
}

Async/Await Patterns

• Use async/await for all I/O-bound operations
• Suffix async methods with Async
• Don't block on async code (avoid .Result and .Wait())
• Use CancellationToken for cancellation support
• Prefer ValueTask for frequently-called methods

Entity Framework Core

Configuration

• Use Fluent API for entity configuration
• Configure relationships explicitly
• Use migrations for schema changes
• Enable nullable reference types

Best Practices

• Use AsNoTracking() for read-only queries
• Implement the Repository pattern for data access
• Use Include/ThenInclude for eager loading
• Avoid N+1 query problems
• Use projections for optimized queries

public async Task<IEnumerable<UserDto>> GetUsersAsync()
{
    return await _context.Users
        .AsNoTracking()
        .Select(u => new UserDto
        {
            Id = u.Id,
            Name = u.Name
        })
        .ToListAsync();
}

Dependency Injection

• Use constructor injection
• Register services in Program.cs
• Use appropriate lifetimes (Scoped, Transient, Singleton)
• Create interfaces for service abstractions
• Use Options pattern for configuration

builder.Services.AddScoped<IUserService, UserService>();
builder.Services.Configure<JwtSettings>(builder.Configuration.GetSection("Jwt"));

Caching

• Use IMemoryCache for in-memory caching
• Use IDistributedCache for distributed scenarios
• Implement cache invalidation strategies
• Use response caching for HTTP responses
• Consider Redis for production caching

Validation

• Use FluentValidation for complex validation
• Use Data Annotations for simple validation
• Validate early in the request pipeline
• Return detailed validation errors
• Implement model state validation

Error Handling

• Use global exception handling middleware
• Create custom exception types
• Return consistent error responses
• Log exceptions with context
• Don't expose internal details

Security

Authentication

• Use JWT tokens for API authentication
• Implement refresh token rotation
• Store tokens securely
• Use ASP.NET Core Identity when appropriate

Authorization

• Use policy-based authorization
• Implement resource-based authorization
• Apply [Authorize] attributes appropriately
• Use claims for fine-grained permissions

Testing

• Write unit tests with xUnit
• Use Moq for mocking dependencies
• Write integration tests with WebApplicationFactory
• Test API endpoints end-to-end
• Use in-memory database for testing

Documentation

• Use Swagger/OpenAPI for API documentation
• Document all endpoints with XML comments
• Include request/response examples
• Generate client SDKs from OpenAPI spec