claudemd

CLAUDE.md for ASP.NET Core Web API

Configure workspace rules for complex .NET solutions. Establish strict parameters for EF Core, WebApplicationFactory, DTO mappings, and Nullable contexts.

Why .NET solutions need custom rules

ASP.NET Core Web API solutions are typically structured across multiple nested projects (Core, Infrastructure, Web API, Integration Tests). Without explicit instructions inside your CLAUDE.md, Claude Code will:

  • Execute generic dotnet CLI lines: Running commands in the wrong directory or solution file.
  • Return raw EF Core Entities: Exposing DB models straight from API endpoints instead of mapping to clean DTOs.
  • Mishandle Nullability: Ignoring compiler warnings or using the null-forgiving operator (!) inappropriately.
  • Fail at DB migrations: Modifying DB context files without creating EF Core migration files.

Architectural Core Standards

1. DTO vs Entity Separation

Database entities (e.g., EF Core models mapping to PostgreSQL or SQL Server tables) must never escape the Application/Infrastructure boundary. All API endpoints must consume and produce Data Transfer Objects (DTOs) or API Models. This ensures changes to database schemas do not break downstream API consumers.

2. Entity Framework Core Lifecycle & Migrations

Prevent raw SQL execution or manual database modifications. All schema updates must happen through EF Core Migrations generated via the .NET CLI. Explicit commands should be mapped inside CLAUDE.md to target the Infrastructure project (carrying the DB Context) and the Startup project.

3. Testing Context (xUnit & WebApplicationFactory)

Instead of mocking DbContext directly, integration tests must execute against an in-memory database or SQLite engine using ASP.NET Core's WebApplicationFactory<TStartup>. This validates routing, JSON serialization/deserialization, validation filters, and database triggers.

4. Nullable Reference Types Context

All projects must enforce <Nullable>enable</Nullable> inside their .csproj. Claude must write code that respects nullability warnings. The null-forgiving operator (!) is prohibited unless setting up EF Core navigation properties where the database guarantees values.

The .NET Web API CLAUDE.md Template

Copy the file below into the root of your multi-project .NET solution:

# Build and Test Commands
- Build solution: `dotnet build MySolution.sln`
- Run local web api: `dotnet run --project src/MyProject.Api`
- Run all tests: `dotnet test`
- Run single test project: `dotnet test tests/MyProject.IntegrationTests`
- Add database migration: `dotnet ef migrations add [migration_name] --project src/MyProject.Infrastructure --startup-project src/MyProject.Api`
- Update database: `dotnet ef database update --project src/MyProject.Infrastructure --startup-project src/MyProject.Api`

# Code Style Guidelines
- Solution layout: Core (Entities/Interfaces), Application (DTOs/Services), Infrastructure (EF/Auth), Api (Controllers/Configurations).
- Coding standards: Use strict C# 12 conventions (Primary Constructors where applicable).
- Nullability: `#nullable enable` must be active. Respect compiler warning annotations. Do not use `!` to bypass warning flags.
- Controllers: Always inherit from `ControllerBase`. Apply `[ApiController]` and explicit `[Route("api/[controller]")]` parameters.
- Data Mappings: Databases entities must be mapped to DTO records inside Application services. Never return DB models directly from Controllers.
- EF Core: Place all Fluent API configurations under Infrastructure's DB Context class. Never configure inline schemas in entities.
- Async patterns: Return Task or Task<ActionResult> on async controller actions. Suffix async methods with `Async`.
- Azure setups: Bind configurations using Options pattern. Use `DefaultAzureCredential` when configuring Key Vault connections.

# Testing Conventions
- Framework: Use xUnit and FluentAssertions.
- Integration tests: Configure test database using SQLite in-memory or SQLite files. Use `WebApplicationFactory` to build test server context.
- Mocking: Use Moq or NSubstitute only to mock external HTTP integrations.

# Ignore Paths
- Global excludes: Exclude `bin/`, `obj/`, `.vs/`, `.idea/`, and EF migration snapshot cache.

Common Pitfalls & Resolutions

  • EF Core Migration Failures: If Claude Code tries to run EF commands without specifying the correct Infrastructure project flag, the command will fail. The commands section above guarantees it calls the migrations correctly.
  • Database Context Lifecycles: Enforce that DbContext is injected with scoped lifetimes (default) to prevent concurrency leaks during async execution.