csharp

name	csharp
description	| Use when this capability is needed.

C# 12 - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: csharp for comprehensive documentation.

Records

// Positional record (immutable)
public record UserDto(int Id, string Name, string Email);

// Record with additional members
public record OrderDto(int Id, decimal Total)
{
    public string FormattedTotal => Total.ToString("C");
}

// Record struct (value type, C# 10)
public readonly record struct Point(double X, double Y);

// With-expression (non-destructive mutation)
var updated = user with { Name = "New Name" };

Pattern Matching (C# 12)

// Switch expression
string GetDiscount(Customer customer) => customer switch
{
    { Type: CustomerType.Premium, YearsActive: > 5 } => "30%",
    { Type: CustomerType.Premium } => "20%",
    { Type: CustomerType.Regular, YearsActive: > 3 } => "10%",
    _ => "0%",
};

// List patterns (C# 11)
var result = numbers switch
{
    [1, 2, 3] => "exact match",
    [1, .., 3] => "starts with 1, ends with 3",
    [_, > 5, ..] => "second element > 5",
    [] => "empty",
    _ => "other",
};

// Type pattern with when
if (shape is Circle { Radius: > 10 } circle)
{
    Console.WriteLine($"Large circle: {circle.Radius}");
}

Nullable Reference Types

// Enable in .csproj: <Nullable>enable</Nullable>

public class UserService
{
    // Nullable return type
    public User? FindById(int id) => _users.FirstOrDefault(u => u.Id == id);

    // Non-nullable parameter
    public void Update(User user)
    {
        ArgumentNullException.ThrowIfNull(user);
        // user is guaranteed non-null here
    }

    // Null-conditional and coalescing
    public string GetDisplayName(User? user)
        => user?.Name ?? "Unknown";

    // Required members (C# 11)
    public required string Name { get; init; }
}

Async/Await Patterns

// Basic async method
public async Task<User> GetUserAsync(int id)
{
    var user = await _repository.FindAsync(id);
    return user ?? throw new NotFoundException($"User {id} not found");
}

// Parallel async
public async Task<(User[], Order[])> GetDashboardDataAsync(int userId)
{
    var usersTask = _userService.GetAllAsync();
    var ordersTask = _orderService.GetByUserAsync(userId);
    await Task.WhenAll(usersTask, ordersTask);
    return (usersTask.Result, ordersTask.Result);
}

// IAsyncEnumerable
public async IAsyncEnumerable<User> GetUsersStreamAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var user in _context.Users.AsAsyncEnumerable().WithCancellation(ct))
    {
        yield return user;
    }
}

// ValueTask for hot paths
public ValueTask<User?> GetCachedUserAsync(int id)
{
    if (_cache.TryGetValue(id, out var user))
        return ValueTask.FromResult<User?>(user);
    return  ValueTask<User?>(LoadUserAsync(id));
}

LINQ

// Method syntax (preferred)
var result = users
    .Where(u => u.IsActive)
    .OrderBy(u => u.Name)
    .Select(u => new { u.Name, u.Email })
    .ToList();

// GroupBy
var grouped = orders
    .GroupBy(o => o.Status)
    .Select(g => new { Status = g.Key, Count = g.Count(), Total = g.Sum(o => o.Amount) });

// Aggregate
var summary = orders.Aggregate(
    new { Count = 0, Total = 0m },
    (acc, order) => new { Count = acc.Count + 1, Total = acc.Total + order.Amount });

// Chunk (C# 12 / .NET 8)
var batches = users.Chunk(100); // IEnumerable<User[]>

Primary Constructors (C# 12)

// Class primary constructor
public class UserService(IUserRepository repository, ILogger<UserService> logger)
{
    public async Task<User> GetByIdAsync(int id)
    {
        logger.LogInformation("Getting user {Id}", id);
        return await repository.GetByIdAsync(id)
            ?? throw new NotFoundException($"User {id} not found");
    }
}

// Record primary constructor (already existed)
public record UserDto(int Id, string Name, string Email);

Collection Expressions (C# 12)

// Array
int[] numbers = [1, 2, 3, 4, 5];

// List
List<string> names = ["Alice", "Bob", "Charlie"];

// Spread
int[] first = [1, 2, 3];
int[] second = [4, 5, 6];
int[] combined = [..first, ..second]; // [1, 2, 3, 4, 5, 6]

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
.Result / .Wait()	Deadlocks	Use async/await
async void	Exceptions lost	Use async Task
Mutable DTOs	Unexpected mutations	Use record types
No null checking	NullReferenceException	Enable nullable references
String concatenation in loops	Memory pressure	Use StringBuilder

Quick Troubleshooting

Issue	Likely Cause	Solution
Nullable warning	Missing null check	Add ?, ??, or null guard
Deadlock	.Result in async context	Use await
LINQ multiple enumeration	Iterating IEnumerable twice	Call .ToList() first
Record equality fails	Reference type property	Override Equals or use value types

---

Source: claude-dev-suite/claude-dev-suite — distributed by TomeVault.