.NET Architect Helper

Your agent for .NET application architecture — covering ASP.NET Core, Entity Framework, clean architecture patterns, and modern C# best practices for enterprise development.

When to Use This Agent

Choose .NET Architect Helper when:

• Designing ASP.NET Core application architecture (Web API, MVC, Blazor)
• Implementing clean architecture, CQRS, or domain-driven design in .NET
• Structuring Entity Framework Core data access patterns
• Setting up dependency injection, middleware pipelines, and configuration
• Reviewing .NET code for architectural consistency and best practices

Consider alternatives when:

• You need Azure-specific infrastructure — use an Azure specialist agent
• You need frontend architecture (React, Angular) — use a frontend agent
• You need .NET MAUI or WinForms — use a desktop development agent

Quick Start

Copy
# .claude/agents/dotnet-architect.yml
name: .NET Architect Helper
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: .NET architecture agent for ASP.NET Core design, clean architecture, EF Core, and C# best practices

Example invocation:

claude "Set up a clean architecture project structure for our ASP.NET Core Web API with CQRS using MediatR, Entity Framework Core, and FluentValidation"

Core Concepts

Clean Architecture in .NET

Solution/
├── src/
│   ├── Domain/                    # Enterprise business rules
│   │   ├── Entities/              # Business objects
│   │   ├── ValueObjects/          # Immutable value types
│   │   ├── Enums/                 # Domain enumerations
│   │   └── Interfaces/            # Repository contracts
│   ├── Application/               # Application business rules
│   │   ├── Features/              # CQRS commands and queries
│   │   ├── Interfaces/            # Service contracts
│   │   ├── DTOs/                  # Data transfer objects
│   │   └── Behaviors/             # Pipeline behaviors (validation, logging)
│   ├── Infrastructure/            # External concerns
│   │   ├── Persistence/           # EF Core, repositories
│   │   ├── Services/              # External service implementations
│   │   └── Identity/              # Authentication/authorization
│   └── WebAPI/                    # Presentation layer
│       ├── Controllers/           # API endpoints
│       ├── Middleware/            # Request pipeline
│       └── Program.cs            # App configuration
└── tests/
    ├── Domain.Tests/
    ├── Application.Tests/
    └── WebAPI.Tests/

Key .NET Patterns

Pattern	Library	Purpose
CQRS	MediatR	Separate read/write operations
Validation	FluentValidation	Request validation pipeline
ORM	EF Core	Database access and migrations
Mapping	AutoMapper / Mapster	DTO ↔ Entity mapping
DI	Built-in Microsoft.Extensions.DI	Dependency injection
Logging	Serilog	Structured logging
Auth	Microsoft.Identity.Web	Entra ID authentication

Configuration

Parameter	Description	Default
architecture_pattern	Architecture style (clean, vertical-slice, modular-monolith)	clean
dotnet_version	Target .NET version	8.0
cqrs_library	CQRS framework (mediatr, wolverine, custom)	mediatr
orm	Data access (ef-core, dapper, both)	ef-core
auth_method	Authentication (jwt, entra-id, identity)	entra-id

Best Practices

1. Keep the Domain layer free of dependencies. The Domain project should reference zero external packages — no EF Core, no MediatR, no AutoMapper. Domain entities and interfaces depend only on .NET base types. This keeps your business logic portable and testable.

2. Use MediatR pipeline behaviors for cross-cutting concerns. Implement validation, logging, caching, and transaction management as MediatR behaviors instead of scattering them through handlers. This applies concerns consistently without polluting business logic.

3. Configure services in extension methods, not directly in Program.cs. Create AddInfrastructure(), AddApplication(), and AddPersistence() extension methods. This keeps Program.cs clean and makes each layer's configuration independently testable.

4. Use strongly-typed IDs for domain entities. Instead of int or Guid for entity IDs, create dedicated types like OrderId. This prevents accidentally passing an OrderId where a CustomerId is expected, catching bugs at compile time.

5. Implement the Repository pattern over EF Core's DbContext. While EF Core is already a Unit of Work/Repository, wrapping it with domain-specific repository interfaces keeps infrastructure details out of your application layer and makes testing with mocks straightforward.

Common Issues

EF Core navigation properties cause circular serialization. When returning entities directly from API endpoints, navigation properties create circular JSON references. Always map entities to DTOs before returning from controllers, and configure JsonSerializerOptions to handle reference cycles.

MediatR handlers become bloated with cross-cutting logic. When handlers contain validation, logging, caching, and business logic, they're doing too much. Extract cross-cutting concerns into pipeline behaviors (IPipelineBehavior<TRequest, TResponse>) that run automatically for every request.

Dependency injection registration becomes unmanageable. Large projects with hundreds of services create massive DI registration code. Use assembly scanning (services.AddMediatR(assembly), services.Scan() from Scrutor) to register services by convention instead of individually.