Dotnet Patterns

1---2name: dotnet-patterns3description: Idiomatic C# and .NET patterns, conventions, dependency injection, async/await, and best practices for building robust, maintainable .NET applications.4origin: ECC5---6 7# .NET Development Patterns8 9Idiomatic C# and .NET patterns for building robust, performant, and maintainable applications.10 11## When to Activate12 13- Writing new C# code14- Reviewing C# code15- Refactoring existing .NET applications16- Designing service architectures with ASP.NET Core17 18## Core Principles19 20### 1. Prefer Immutability21 22Use records and init-only properties for data models. Mutability should be an explicit, justified choice.23 24```csharp25// Good: Immutable value object26public sealed record Money(decimal Amount, string Currency);27 28// Good: Immutable DTO with init setters29public sealed class CreateOrderRequest30{31    public required string CustomerId { get; init; }32    public required IReadOnlyList<OrderItem> Items { get; init; }33}34 35// Bad: Mutable model with public setters36public class Order37{38    public string CustomerId { get; set; }39    public List<OrderItem> Items { get; set; }40}41```42 43### 2. Explicit Over Implicit44 45Be clear about nullability, access modifiers, and intent.46 47```csharp48// Good: Explicit access modifiers and nullability49public sealed class UserService50{51    private readonly IUserRepository _repository;52    private readonly ILogger<UserService> _logger;53 54    public UserService(IUserRepository repository, ILogger<UserService> logger)55    {56        _repository = repository ?? throw new ArgumentNullException(nameof(repository));57        _logger = logger ?? throw new ArgumentNullException(nameof(logger));58    }59 60    public async Task<User?> FindByIdAsync(Guid id, CancellationToken cancellationToken)61    {62        return await _repository.FindByIdAsync(id, cancellationToken);63    }64}65```66 67### 3. Depend on Abstractions68 69Use interfaces for service boundaries. Register via DI container.70 71```csharp72// Good: Interface-based dependency73public interface IOrderRepository74{75    Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken);76    Task<IReadOnlyList<Order>> FindByCustomerAsync(string customerId, CancellationToken cancellationToken);77    Task AddAsync(Order order, CancellationToken cancellationToken);78}79 80// Registration81builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();82```83 84## Async/Await Patterns85 86### Proper Async Usage87 88```csharp89// Good: Async all the way, with CancellationToken90public async Task<OrderSummary> GetOrderSummaryAsync(91    Guid orderId,92    CancellationToken cancellationToken)93{94    var order = await _repository.FindByIdAsync(orderId, cancellationToken)95        ?? throw new NotFoundException($"Order {orderId} not found");96 97    var customer = await _customerService.GetAsync(order.CustomerId, cancellationToken);98 99    return new OrderSummary(order, customer);100}101 102// Bad: Blocking on async103public OrderSummary GetOrderSummary(Guid orderId)104{105    var order = _repository.FindByIdAsync(orderId, CancellationToken.None).Result; // Deadlock risk106    return new OrderSummary(order);107}108```109 110### Parallel Async Operations111 112```csharp113// Good: Concurrent independent operations114public async Task<DashboardData> LoadDashboardAsync(CancellationToken cancellationToken)115{116    var ordersTask = _orderService.GetRecentAsync(cancellationToken);117    var metricsTask = _metricsService.GetCurrentAsync(cancellationToken);118    var alertsTask = _alertService.GetActiveAsync(cancellationToken);119 120    await Task.WhenAll(ordersTask, metricsTask, alertsTask);121 122    return new DashboardData(123        Orders: await ordersTask,124        Metrics: await metricsTask,125        Alerts: await alertsTask);126}127```128 129## Options Pattern130 131Bind configuration sections to strongly-typed objects.132 133```csharp134public sealed class SmtpOptions135{136    public const string SectionName = "Smtp";137 138    public required string Host { get; init; }139    public required int Port { get; init; }140    public required string Username { get; init; }141    public bool UseSsl { get; init; } = true;142}143 144// Registration145builder.Services.Configure<SmtpOptions>(146    builder.Configuration.GetSection(SmtpOptions.SectionName));147 148// Usage via injection149public class EmailService(IOptions<SmtpOptions> options)150{151    private readonly SmtpOptions _smtp = options.Value;152}153```154 155## Result Pattern156 157Return explicit success/failure instead of throwing for expected failures.158 159```csharp160public sealed record Result<T>161{162    public bool IsSuccess { get; }163    public T? Value { get; }164    public string? Error { get; }165 166    private Result(T value) { IsSuccess = true; Value = value; }167    private Result(string error) { IsSuccess = false; Error = error; }168 169    public static Result<T> Success(T value) => new(value);170    public static Result<T> Failure(string error) => new(error);171}172 173// Usage174public async Task<Result<Order>> PlaceOrderAsync(CreateOrderRequest request)175{176    if (request.Items.Count == 0)177        return Result<Order>.Failure("Order must contain at least one item");178 179    var order = Order.Create(request);180    await _repository.AddAsync(order, CancellationToken.None);181    return Result<Order>.Success(order);182}183```184 185## Repository Pattern with EF Core186 187```csharp188public sealed class SqlOrderRepository : IOrderRepository189{190    private readonly AppDbContext _db;191 192    public SqlOrderRepository(AppDbContext db) => _db = db;193 194    public async Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken)195    {196        return await _db.Orders197            .Include(o => o.Items)198            .AsNoTracking()199            .FirstOrDefaultAsync(o => o.Id == id, cancellationToken);200    }201 202    public async Task<IReadOnlyList<Order>> FindByCustomerAsync(203        string customerId,204        CancellationToken cancellationToken)205    {206        return await _db.Orders207            .Where(o => o.CustomerId == customerId)208            .OrderByDescending(o => o.CreatedAt)209            .AsNoTracking()210            .ToListAsync(cancellationToken);211    }212 213    public async Task AddAsync(Order order, CancellationToken cancellationToken)214    {215        _db.Orders.Add(order);216        await _db.SaveChangesAsync(cancellationToken);217    }218}219```220 221## Middleware and Pipeline222 223```csharp224// Custom middleware225public sealed class RequestTimingMiddleware226{227    private readonly RequestDelegate _next;228    private readonly ILogger<RequestTimingMiddleware> _logger;229 230    public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)231    {232        _next = next;233        _logger = logger;234    }235 236    public async Task InvokeAsync(HttpContext context)237    {238        var stopwatch = Stopwatch.StartNew();239        try240        {241            await _next(context);242        }243        finally244        {245            stopwatch.Stop();246            _logger.LogInformation(247                "Request {Method} {Path} completed in {ElapsedMs}ms with status {StatusCode}",248                context.Request.Method,249                context.Request.Path,250                stopwatch.ElapsedMilliseconds,251                context.Response.StatusCode);252        }253    }254}255```256 257## Minimal API Patterns258 259```csharp260// Organized with route groups261var orders = app.MapGroup("/api/orders")262    .RequireAuthorization()263    .WithTags("Orders");264 265orders.MapGet("/{id:guid}", async (266    Guid id,267    IOrderRepository repository,268    CancellationToken cancellationToken) =>269{270    var order = await repository.FindByIdAsync(id, cancellationToken);271    return order is not null272        ? TypedResults.Ok(order)273        : TypedResults.NotFound();274});275 276orders.MapPost("/", async (277    CreateOrderRequest request,278    IOrderService service,279    CancellationToken cancellationToken) =>280{281    var result = await service.PlaceOrderAsync(request, cancellationToken);282    return result.IsSuccess283        ? TypedResults.Created($"/api/orders/{result.Value!.Id}", result.Value)284        : TypedResults.BadRequest(result.Error);285});286```287 288## Guard Clauses289 290```csharp291// Good: Early returns with clear validation292public async Task<ProcessResult> ProcessPaymentAsync(293    PaymentRequest request,294    CancellationToken cancellationToken)295{296    ArgumentNullException.ThrowIfNull(request);297 298    if (request.Amount <= 0)299        throw new ArgumentOutOfRangeException(nameof(request.Amount), "Amount must be positive");300 301    if (string.IsNullOrWhiteSpace(request.Currency))302        throw new ArgumentException("Currency is required", nameof(request.Currency));303 304    // Happy path continues here without nesting305    var gateway = _gatewayFactory.Create(request.Currency);306    return await gateway.ChargeAsync(request, cancellationToken);307}308```309 310## Anti-Patterns to Avoid311 312| Anti-Pattern | Fix |313|---|---|314| `async void` methods | Return `Task` (except event handlers) |315| `.Result` or `.Wait()` | Use `await` |316| `catch (Exception) { }` | Handle or rethrow with context |317| `new Service()` in constructors | Use constructor injection |318| `public` fields | Use properties with appropriate accessors |319| `dynamic` in business logic | Use generics or explicit types |320| Mutable `static` state | Use DI scoping or `ConcurrentDictionary` |321| `string.Format` in loops | Use `StringBuilder` or interpolated string handlers |