C# and .NET Best Practices
Master comprehensive C# and .NET development practices for building robust, maintainable, secure, and performant enterprise applications following modern standards (2024-2026).
When to Use This Skill
- Developing new .NET APIs, services, or applications
- Reviewing C# code for quality and performance
- Establishing team coding standards and guidelines
- Implementing Clean Architecture patterns
- Optimizing .NET application performance
- Setting up dependency injection properly
- Writing comprehensive unit and integration tests
- Migrating to modern C# features (12+) and .NET 8/9
Core Concepts
1. Clean Architecture Structure
src/
├── Domain/ # Core business logic (no external dependencies)
│ ├── Entities/ # Business entities
│ ├── ValueObjects/ # Immutable value types
│ ├── Enums/ # Domain enumerations
│ ├── Exceptions/ # Domain-specific exceptions
│ ├── Interfaces/ # Repository and service interfaces
│ └── Events/ # Domain events
├── Application/ # Use cases and orchestration
│ ├── Common/
│ │ ├── Interfaces/ # Application service interfaces
│ │ ├── Behaviors/ # MediatR pipeline behaviors
│ │ └── Mappings/ # AutoMapper profiles
│ ├── Features/ # Vertical slices by feature
│ │ └── Orders/
│ │ ├── Commands/
│ │ ├── Queries/
│ │ └── DTOs/
│ └── DependencyInjection.cs
├── Infrastructure/ # External concerns implementation
│ ├── Data/
│ │ ├── AppDbContext.cs
│ │ ├── Configurations/ # EF Core configurations
│ │ └── Repositories/
│ ├── Services/
│ │ ├── DateTimeService.cs
│ │ └── EmailService.cs
│ └── DependencyInjection.cs
└── Api/ # Presentation layer
├── Controllers/ # Or Minimal API endpoints
├── Middleware/
├── Filters/
└── Program.cs
2. Modern C# 12+ Features
// Primary Constructors (C# 12)
public class UserService(
IUserRepository repository,
ILogger<UserService> logger,
IOptions<UserOptions> options)
{
private readonly UserOptions _options = options.Value;
public async Task<User?> GetByIdAsync(string id, CancellationToken ct = default)
{
logger.LogInformation("Fetching user {UserId}", id);
return await repository.GetByIdAsync(id, ct);
}
}
// Records for immutable data and DTOs
public record UserDto(
string Id,
string Name,
string Email,
DateTimeOffset CreatedAt);
// Record with computed property
public record OrderSummary(
string OrderId,
List<OrderItemDto> Items,
decimal DiscountPercent)
{
public decimal Subtotal => Items.Sum(i => i.Quantity * i.UnitPrice);
public decimal Total => Subtotal * (1 - DiscountPercent);
}
// Collection expressions (C# 12)
List<int> numbers = [1, 2, 3, 4, 5];
int[] moreNumbers = [.. numbers, 6, 7, 8]; // Spread operator
ReadOnlySpan<string> names = ["Alice", "Bob", "Charlie"];
// Required members (C# 11)
public class Configuration
{
public required string ConnectionString { get; init; }
public required string ApiKey { get; init; }
public int Timeout { get; init; } = 30;
}
// File-scoped namespaces and types
file class InternalHelper // Only visible in this file
{
public static string Format(string input) => input.Trim().ToLower();
}
// Pattern matching enhancements
public static string GetDiscount(object customer) => customer switch
{
{ } c when c is PremiumCustomer { LoyaltyYears: > 5 } => "30%",
PremiumCustomer { LoyaltyYears: > 2 } => "20%",
PremiumCustomer => "10%",
RegisteredCustomer => "5%",
_ => "0%"
};
// List patterns (C# 11)
public static decimal CalculateAverage(int[] numbers) => numbers switch
{
[] => 0,
[var single] => single,
[var first, .. var rest] => (first + rest.Sum()) / (1 + rest.Length)
};
// Raw string literals
var json = """
{
"name": "John",
"email": "john@example.com",
"roles": ["admin", "user"]
}
""";
// Interpolated raw strings
var sql = $"""
SELECT Id, Name, Email
FROM Users
WHERE IsActive = 1
AND CreatedAt > '{DateTime.UtcNow:yyyy-MM-dd}'
""";
3. Async/Await Best Practices
// ✅ CORRECT: Async all the way down
public async Task<Order> GetOrderAsync(int id, CancellationToken ct = default)
{
return await _repository.GetByIdAsync(id, ct);
}
// ✅ CORRECT: Parallel execution with WhenAll
public async Task<(Customer Customer, List<Order> Orders)> GetCustomerWithOrdersAsync(
int customerId,
CancellationToken ct = default)
{
var customerTask = _customerRepository.GetByIdAsync(customerId, ct);
var ordersTask = _orderRepository.GetByCustomerIdAsync(customerId, ct);
await Task.WhenAll(customerTask, ordersTask);
return (await customerTask, await ordersTask);
}
// ✅ CORRECT: ValueTask for hot paths
public ValueTask<Product?> GetCachedProductAsync(string id)
{
if (_cache.TryGetValue(id, out Product? product))
{
return ValueTask.FromResult(product);
}
return new ValueTask<Product?>(LoadFromDatabaseAsync(id));
}
// ✅ CORRECT: ConfigureAwait in libraries
public async Task<T> LibraryMethodAsync<T>(string url, CancellationToken ct = default)
{
var response = await _httpClient.GetAsync(url, ct).ConfigureAwait(false);
response.EnsureSuccessStatusCode();
return await response.Content.ReadFromJsonAsync<T>(ct).ConfigureAwait(false);
}
// ✅ CORRECT: Cancellation token usage
public async Task ProcessBatchAsync(
IEnumerable<string> items,
CancellationToken ct = default)
{
foreach (var item in items)
{
ct.ThrowIfCancellationRequested();
await ProcessItemAsync(item, ct);
}
}
// ❌ WRONG: Blocking on async (causes deadlock)
public User GetUser(int id)
{
// NEVER DO THIS
return GetUserAsync(id).Result;
// OR
return GetUserAsync(id).GetAwaiter().GetResult();
}
// ❌ WRONG: async void (except event handlers)
public async void ProcessOrder(Order order) // Exceptions are lost!
{
await _orderService.ProcessAsync(order);
}
// ❌ WRONG: Unnecessary Task.Run
await Task.Run(async () => await GetDataAsync()); // Wastes a thread
4. Dependency Injection Patterns
// Service registration extension
public static class DependencyInjection
{
public static IServiceCollection AddApplicationServices(
this IServiceCollection services,
IConfiguration configuration)
{
// Scoped: One instance per HTTP request
services.AddScoped<IOrderService, OrderService>();
services.AddScoped<ICustomerRepository, CustomerRepository>();
// Singleton: One instance for entire application lifetime
services.AddSingleton<IConnectionMultiplexer>(_ =>
ConnectionMultiplexer.Connect(configuration["Redis:Connection"]!));
services.AddSingleton<ICacheService, RedisCacheService>();
// Transient: New instance every time resolved
services.AddTransient<IValidator<CreateOrderCommand>, CreateOrderValidator>();
// Options pattern
services.Configure<EmailOptions>(configuration.GetSection("Email"));
services.AddOptions<DatabaseOptions>()
.Bind(configuration.GetSection("Database"))
.ValidateDataAnnotations()
.ValidateOnStart();
// Keyed services (.NET 8+)
services.AddKeyedScoped<IPaymentProcessor, StripeProcessor>("stripe");
services.AddKeyedScoped<IPaymentProcessor, PayPalProcessor>("paypal");
// Factory pattern for conditional resolution
services.AddScoped<IPricingStrategy>(sp =>
{
var options = sp.GetRequiredService<IOptions<PricingOptions>>().Value;
return options.UseNewEngine
? sp.GetRequiredService<NewPricingStrategy>()
: sp.GetRequiredService<LegacyPricingStrategy>();
});
// Decorator pattern
services.AddScoped<IUserRepository, UserRepository>();
services.Decorate<IUserRepository, CachedUserRepository>();
return services;
}
}
// Usage with keyed services
public class CheckoutService(
[FromKeyedServices("stripe")] IPaymentProcessor stripeProcessor,
[FromKeyedServices("paypal")] IPaymentProcessor paypalProcessor)
{
public async Task<bool> ProcessAsync(string provider, decimal amount)
{
var processor = provider switch
{
"stripe" => stripeProcessor,
"paypal" => paypalProcessor,
_ => throw new ArgumentException($"Unknown provider: {provider}")
};
return await processor.ChargeAsync(amount);
}
}
// Options pattern with validation
public class EmailOptions
{
public const string SectionName = "Email";
[Required]
public string SmtpServer { get; init; } = string.Empty;
[Range(1, 65535)]
public int Port { get; init; } = 587;
[Required, EmailAddress]
public string FromAddress { get; init; } = string.Empty;
public bool UseSsl { get; init; } = true;
}
5. Entity Framework Core Best Practices
// DbContext configuration
public class AppDbContext(DbContextOptions<AppDbContext> options)
: DbContext(options)
{
public DbSet<Order> Orders => Set<Order>();
public DbSet<Customer> Customers => Set<Customer>();
public DbSet<Product> Products => Set<Product>();
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
// Apply all configurations from assembly
modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
// Global query filters
modelBuilder.Entity<Order>().HasQueryFilter(o => !o.IsDeleted);
// Indexes
modelBuilder.Entity<Customer>()
.HasIndex(c => c.Email)
.IsUnique();
}
public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
{
// Audit tracking
foreach (var entry in ChangeTracker.Entries<IAuditable>())
{
switch (entry.State)
{
case EntityState.Added:
entry.Entity.CreatedAt = DateTime.UtcNow;
break;
case EntityState.Modified:
entry.Entity.ModifiedAt = DateTime.UtcNow;
break;
}
}
return await base.SaveChangesAsync(ct);
}
}
// Entity configuration
public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
public void Configure(EntityTypeBuilder<Order> builder)
{
builder.ToTable("Orders");
builder.HasKey(o => o.Id);
builder.Property(o => o.Id)
.HasConversion<OrderId.EfCoreValueConverter>();
builder.Property(o => o.TotalAmount)
.HasPrecision(18, 2);
builder.Property(o => o.Status)
.HasConversion<string>()
.HasMaxLength(50);
// Owned type for value object
builder.OwnsOne(o => o.ShippingAddress, address =>
{
address.Property(a => a.Street).HasMaxLength(200);
address.Property(a => a.City).HasMaxLength(100);
address.Property(a => a.PostalCode).HasMaxLength(20);
});
builder.HasMany(o => o.Items)
.WithOne()
.HasForeignKey(i => i.OrderId)
.OnDelete(DeleteBehavior.Cascade);
builder.HasIndex(o => new { o.CustomerId, o.CreatedAt });
}
}
// Repository with EF Core
public class OrderRepository(AppDbContext context) : IOrderRepository
{
// ✅ CORRECT: AsNoTracking for read-only queries
public async Task<Order?> GetByIdAsync(OrderId id, CancellationToken ct = default)
{
return await context.Orders
.AsNoTracking()
.Include(o => o.Items)
.FirstOrDefaultAsync(o => o.Id == id, ct);
}
// ✅ CORRECT: Projection to DTO
public async Task<List<OrderSummaryDto>> GetSummariesAsync(
int customerId,
CancellationToken ct = default)
{
return await context.Orders
.AsNoTracking()
.Where(o => o.CustomerId == customerId)
.Select(o => new OrderSummaryDto(
o.Id.Value,
o.TotalAmount,
o.Status,
o.CreatedAt))
.ToListAsync(ct);
}
// ✅ CORRECT: Efficient bulk operations (EF Core 7+)
public async Task<int> DeactivateOldOrdersAsync(
DateTime cutoff,
CancellationToken ct = default)
{
return await context.Orders
.Where(o => o.CreatedAt < cutoff && o.Status == OrderStatus.Draft)
.ExecuteUpdateAsync(s => s
.SetProperty(o => o.IsDeleted, true)
.SetProperty(o => o.DeletedAt, DateTime.UtcNow),
ct);
}
// ❌ WRONG: Loading entire entity when only need ID
// var order = await context.Orders.FirstOrDefaultAsync(o => o.CustomerId == id);
// return order?.Id;
}
6. Error Handling and Validation
// Global exception handler (Minimal API)
public class GlobalExceptionHandler : IExceptionHandler
{
private readonly ILogger<GlobalExceptionHandler> _logger;
public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
{
_logger = logger;
}
public async ValueTask<bool> TryHandleAsync(
HttpContext context,
Exception exception,
CancellationToken ct)
{
_logger.LogError(exception, "Unhandled exception occurred");
var problemDetails = exception switch
{
ValidationException ve => new ProblemDetails
{
Status = StatusCodes.Status400BadRequest,
Title = "Validation Error",
Detail = string.Join("; ", ve.Errors.Select(e => e.ErrorMessage)),
Type = "https://tools.ietf.org/html/rfc7231#section-6.5.1"
},
NotFoundException nf => new ProblemDetails
{
Status = StatusCodes.Status404NotFound,
Title = "Not Found",
Detail = nf.Message,
Type = "https://tools.ietf.org/html/rfc7231#section-6.5.4"
},
UnauthorizedException => new ProblemDetails
{
Status = StatusCodes.Status401Unauthorized,
Title = "Unauthorized",
Type = "https://tools.ietf.org/html/rfc7235#section-3.1"
},
_ => new ProblemDetails
{
Status = StatusCodes.Status500InternalServerError,
Title = "Internal Server Error",
Type = "https://tools.ietf.org/html/rfc7231#section-6.6.1"
}
};
context.Response.StatusCode = problemDetails.Status ?? 500;
await context.Response.WriteAsJsonAsync(problemDetails, ct);
return true;
}
}
// Result pattern for business logic
public class Result<T>
{
public bool IsSuccess { get; }
public T? Value { get; }
public string? Error { get; }
public string? ErrorCode { get; }
private Result(bool isSuccess, T? value, string? error, string? errorCode)
{
IsSuccess = isSuccess;
Value = value;
Error = error;
ErrorCode = errorCode;
}
public static Result<T> Success(T value) => new(true, value, null, null);
public static Result<T> Failure(string error, string? code = null)
=> new(false, default, error, code);
public Result<TNew> Map<TNew>(Func<T, TNew> mapper) =>
IsSuccess
? Result<TNew>.Success(mapper(Value!))
: Result<TNew>.Failure(Error!, ErrorCode);
public TResult Match<TResult>(
Func<T, TResult> success,
Func<string, TResult> failure) =>
IsSuccess ? success(Value!) : failure(Error!);
}
// FluentValidation
public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
public CreateOrderCommandValidator(IProductRepository productRepository)
{
RuleFor(x => x.CustomerId)
.NotEmpty()
.WithMessage("Customer ID is required");
RuleFor(x => x.Items)
.NotEmpty()
.WithMessage("Order must contain at least one item");
RuleForEach(x => x.Items).SetValidator(new OrderItemValidator());
RuleFor(x => x.ShippingAddress)
.NotNull()
.SetValidator(new AddressValidator());
// Async validation (use sparingly)
RuleForEach(x => x.Items)
.MustAsync(async (item, ct) =>
{
var product = await productRepository.GetByIdAsync(item.ProductId, ct);
return product?.Stock >= item.Quantity;
})
.WithMessage("Insufficient stock for product {PropertyValue}");
}
}
7. Testing Patterns
// Unit test with xUnit and Moq
public class OrderServiceTests
{
private readonly Mock<IOrderRepository> _repositoryMock;
private readonly Mock<IStockService> _stockServiceMock;
private readonly OrderService _sut;
public OrderServiceTests()
{
_repositoryMock = new Mock<IOrderRepository>();
_stockServiceMock = new Mock<IStockService>();
_sut = new OrderService(
_repositoryMock.Object,
_stockServiceMock.Object,
NullLogger<OrderService>.Instance);
}
[Fact]
public async Task CreateOrder_WithValidData_ReturnsSuccess()
{
// Arrange
var command = new CreateOrderCommand
{
CustomerId = 1,
Items = [new OrderItemDto("PROD-1", 2, 10.00m)]
};
_stockServiceMock
.Setup(x => x.CheckStockAsync("PROD-1", 2, It.IsAny<CancellationToken>()))
.ReturnsAsync(true);
_repositoryMock
.Setup(x => x.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()))
.ReturnsAsync(new Order { Id = new OrderId(Guid.NewGuid()) });
// Act
var result = await _sut.CreateOrderAsync(command);
// Assert
Assert.True(result.IsSuccess);
Assert.NotNull(result.Value);
_repositoryMock.Verify(
x => x.CreateAsync(
It.Is<Order>(o => o.CustomerId == 1),
It.IsAny<CancellationToken>()),
Times.Once);
}
[Theory]
[InlineData(0)]
[InlineData(-1)]
[InlineData(-100)]
public async Task CreateOrder_WithInvalidQuantity_ReturnsFailure(int quantity)
{
// Arrange
var command = new CreateOrderCommand
{
CustomerId = 1,
Items = [new OrderItemDto("PROD-1", quantity, 10.00m)]
};
// Act
var result = await _sut.CreateOrderAsync(command);
// Assert
Assert.False(result.IsSuccess);
Assert.Equal("VALIDATION_ERROR", result.ErrorCode);
}
}
// Integration tests with WebApplicationFactory
public class OrdersApiTests : IClassFixture<WebApplicationFactory<Program>>
{
private readonly HttpClient _client;
private readonly WebApplicationFactory<Program> _factory;
public OrdersApiTests(WebApplicationFactory<Program> factory)
{
_factory = factory.WithWebHostBuilder(builder =>
{
builder.ConfigureServices(services =>
{
// Replace with in-memory database
services.RemoveAll<DbContextOptions<AppDbContext>>();
services.AddDbContext<AppDbContext>(options =>
options.UseInMemoryDatabase($"TestDb-{Guid.NewGuid()}"));
// Replace external services with mocks
services.RemoveAll<IEmailService>();
services.AddSingleton<IEmailService, FakeEmailService>();
});
});
_client = _factory.CreateClient();
}
[Fact]
public async Task GetOrder_WhenExists_ReturnsOrder()
{
// Arrange
await SeedTestData();
// Act
var response = await _client.GetAsync("/api/orders/1");
// Assert
response.EnsureSuccessStatusCode();
var order = await response.Content.ReadFromJsonAsync<OrderDto>();
Assert.Equal(1, order!.Id);
}
private async Task SeedTestData()
{
using var scope = _factory.Services.CreateScope();
var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();
context.Orders.Add(new Order { Id = new OrderId(1), CustomerId = 100 });
await context.SaveChangesAsync();
}
}
8. Performance Optimization
// Span and Memory for zero-allocation parsing
public static class HighPerformanceParser
{
public static bool TryParseOrderId(ReadOnlySpan<char> input, out int orderId)
{
// Format: "ORD-12345"
if (input.Length < 5 || !input.StartsWith("ORD-"))
{
orderId = 0;
return false;
}
return int.TryParse(input[4..], out orderId);
}
public static IEnumerable<ReadOnlyMemory<char>> SplitLines(ReadOnlyMemory<char> text)
{
var span = text.Span;
int start = 0;
for (int i = 0; i < span.Length; i++)
{
if (span[i] == '\n')
{
yield return text[start..i];
start = i + 1;
}
}
if (start < span.Length)
{
yield return text[start..];
}
}
}
// ArrayPool for temporary buffers
public class BufferedProcessor
{
public async Task<byte[]> ProcessAsync(Stream input)
{
byte[] buffer = ArrayPool<byte>.Shared.Rent(8192);
try
{
using var output = new MemoryStream();
int bytesRead;
while ((bytesRead = await input.ReadAsync(buffer)) > 0)
{
// Process buffer...
await output.WriteAsync(buffer.AsMemory(0, bytesRead));
}
return output.ToArray();
}
finally
{
ArrayPool<byte>.Shared.Return(buffer);
}
}
}
// Caching with IMemoryCache
public class CachedProductService(
IProductRepository repository,
IMemoryCache cache,
ILogger<CachedProductService> logger)
{
private static readonly TimeSpan CacheDuration = TimeSpan.FromMinutes(5);
public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
{
var cacheKey = $"product:{id}";
if (cache.TryGetValue(cacheKey, out Product? cached))
{
logger.LogDebug("Cache hit for {CacheKey}", cacheKey);
return cached;
}
logger.LogDebug("Cache miss for {CacheKey}", cacheKey);
var product = await repository.GetByIdAsync(id, ct);
if (product is not null)
{
var options = new MemoryCacheEntryOptions()
.SetSlidingExpiration(CacheDuration)
.SetSize(1);
cache.Set(cacheKey, product, options);
}
return product;
}
}
// Compiled regex for performance
public static partial class Validators
{
[GeneratedRegex(@"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")]
public static partial Regex EmailRegex();
[GeneratedRegex(@"^\d{4}-\d{2}-\d{2}$")]
public static partial Regex DateRegex();
public static bool IsValidEmail(string email) => EmailRegex().IsMatch(email);
}
Quick Reference
Lifetime Guidelines
| Service Type |
Lifetime |
Use Case |
| DbContext |
Scoped |
Database access per request |
| HttpClient (via factory) |
Singleton |
HTTP connections |
| Repositories |
Scoped |
Data access per request |
| Business Services |
Scoped |
Request-scoped operations |
| Validators |
Transient |
Stateless validation |
| Configuration |
Singleton |
IOptions |
| Caches |
Singleton |
Shared cache state |
EF Core Performance Checklist
Common Pitfalls
| Pitfall |
Problem |
Solution |
| Captive dependency |
Singleton holding Scoped |
Use factory pattern or make scoped |
| Blocking async |
.Result deadlock |
Async all the way |
| Over-fetching |
Loading full entities |
Use projections |
| No cancellation |
Long operations can't cancel |
Pass CancellationToken |
| Hardcoded config |
Difficult to change |
Use IOptions pattern |
| Generic exceptions |
catch (Exception) |
Catch specific types |
Best Practices Summary
DO
- Use async/await throughout the call stack
- Pass CancellationToken to all async methods
- Use records for DTOs and immutable data
- Apply IOptions pattern for configuration
- Use Result types for expected business failures
- Write unit tests for business logic
- Use FluentValidation for input validation
- Apply global exception handling
- Use AsNoTracking for read-only EF queries
- Cache aggressively with proper invalidation
DON'T
- Block on async with .Result or .Wait()
- Use async void (except event handlers)
- Catch generic Exception without logging
- Hardcode configuration values
- Expose EF entities in API responses
- Ignore CancellationToken parameters
- Create HttpClient manually (use IHttpClientFactory)
- Use service locator pattern
- Mix sync and async code unnecessarily
- Skip validation at API boundaries
Parent Hub
majiayu000