csharp-frameworks

ASP.NET Core Framework Patterns

Clean Architecture Layers

Presentation (API)  →  Application  →  Domain  →  Infrastructure
Controllers/            Commands/       Entities     EF Core DbContext
Minimal APIs            Queries         Value Objs   Repositories
DTOs                    Handlers        Domain Svc   External APIs
Filters                 Validators      Interfaces   Message Bus

• Dependencies flow inward: Infrastructure → Application → Domain
• Domain has ZERO external dependencies
• Application depends only on Domain interfaces
• Infrastructure implements Domain/Application interfaces

CQRS with MediatR

// Command (writes)
public record CreateOrderCommand(string CustomerId, List<OrderItem> Items) : IRequest<Result<OrderId>>;

public class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, Result<OrderId>>
{
    public async Task<Result<OrderId>> Handle(CreateOrderCommand request, CancellationToken ct)
    {
        // Validate → Create entity → Persist → Return
    }
}

// Query (reads)
public record GetOrderQuery(int OrderId) : IRequest<OrderDto?>;

• Commands return Result<T>, queries return DTOs or null
• One handler per command/query — no shared handlers
• Register MediatR: services.AddMediatR(cfg => cfg.RegisterServicesFromAssemblyContaining<Program>());

FluentValidation

public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty().MaximumLength(50);
        RuleFor(x => x.Items).NotEmpty().WithMessage("Order must have at least one item");
        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(i => i.Quantity).GreaterThan(0);
        });
    }
}

• One validator per command/query
• Register with MediatR pipeline behavior for automatic validation

Controller Conventions

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[Produces("application/json")]
public class OrdersController : ControllerBase
{
    private readonly IMediator _mediator;

    [HttpPost]
    [ProducesResponseType(typeof(OrderId), StatusCodes.Status201Created)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> Create([FromBody] CreateOrderCommand command, CancellationToken ct)
    {
        var result = await _mediator.Send(command, ct);
        return result.Match(
            success => CreatedAtAction(nameof(GetById), new { id = success.Value }, success),
            failure => BadRequest(failure.ToProblemDetails())
        );
    }
}

• Use [ApiController] attribute on all controllers
• Use CancellationToken on all async actions
• Return ProblemDetails for errors (RFC 7807)
• Version APIs: api/v1/orders

Middleware Pipeline Order

app.UseExceptionHandler("/error");
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

Authentication (JWT)

• Use AddAuthentication().AddJwtBearer() with proper token validation
• Store secrets in vault — never in appsettings
• Use [Authorize] attribute, never manual token parsing
• Use policy-based authorization for fine-grained access control