C# Cheat Sheet

Top level statements. No class, no Main, one file.

Console.WriteLine("Hello, World!");

The classic full form, still valid everywhere

namespace HelloApp;

class Program
{
    static void Main(string[] args)
    {
        Console.WriteLine("Hello, World!");
    }
}

Async entry point, returns an exit code

static async Task<int> Main(string[] args)
{
    await Task.Delay(100);
    return 0;
}

Write with and without a line break

Console.Write("no newline ");
Console.WriteLine("with newline");

Read a line, then parse it safely

Console.Write("Age: ");
string? input = Console.ReadLine();
if (int.TryParse(input, out int age))
    Console.WriteLine($"Next year: {age + 1}");

Read a single key without waiting for Enter

ConsoleKeyInfo key = Console.ReadKey(intercept: true);
Console.WriteLine($"You pressed {key.Key}");

Command line arguments

// top level statements expose args automatically
foreach (string arg in args)
    Console.WriteLine(arg);

Single line, block and XML documentation

// single line comment

/* block comment
   across lines */

/// <summary>Adds two numbers.</summary>
/// <param name="a">First value.</param>
/// <returns>The sum.</returns>
int Add(int a, int b) => a + b;

Collapsible region, useful in generated files

#region Helpers
// folded in the IDE
#endregion

File scoped namespace, one less level of indentation

namespace MyApp.Services;

public class OrderService { }

Using directives, aliases and static imports

using System.Text;
using Json = System.Text.Json.JsonSerializer;
using static System.Math;

double r = Sqrt(16);          // no Math. prefix
string s = Json.Serialize(r);

Global using, applies to every file in the project

// GlobalUsings.cs
global using System.Collections.Generic;
global using System.Linq;

Alias any type, including generics and arrays

using Matrix = double[,];
using Pair = (int Id, string Name);   // C# 12

Explicit type versus inferred type

int count = 42;
string name = "Ana";
var total = 19.99m;        // inferred as decimal
var items = new List<int>();

Constants and read only fields

const double Pi = 3.14159;        // compile time
static readonly DateTime Start = DateTime.Now;  // run time, set once

Default values and discards

int zero = default;         // 0
string? nothing = default;  // null
_ = ComputeAndIgnore();     // discard the result

Nullable value type, a struct that can hold null

int? maybe = null;
if (maybe.HasValue)
    Console.WriteLine(maybe.Value);

int safe = maybe ?? 0;               // fallback
int forced = maybe!.Value;           // you promise it is not null

Nullable reference types, a compiler contract not a runtime one

#nullable enable
string notNull = "always set";
string? mayBeNull = null;

int len = mayBeNull?.Length ?? 0;    // no exception

Enable it project wide in the csproj

<Nullable>enable</Nullable>

Null guards, one line each

ArgumentNullException.ThrowIfNull(order);
ArgumentException.ThrowIfNullOrWhiteSpace(name);
ObjectDisposedException.ThrowIf(_disposed, this);

Implicit widening versus explicit narrowing

int i = 100;
long l = i;              // implicit, no data loss
double d = 9.87;
int truncated = (int)d;  // explicit, becomes 9

Parsing strings the safe way

int n = int.Parse("42");                 // throws on bad input
bool ok = int.TryParse("7", out int v);  // never throws
Console.WriteLine(n);
Console.WriteLine($"{ok} {v}");

Convert class handles null and rounding differently

int a = Convert.ToInt32("42");
int b = Convert.ToInt32(9.87);   // 10, rounds instead of truncating
int c = Convert.ToInt32(null);   // 0, no exception

Reference conversion with is and as

object box = "text";

if (box is string s1) Console.WriteLine(s1.Length);
string? s2 = box as string;      // null instead of throwing
string s3 = (string)box;         // InvalidCastException if wrong

Boxing and unboxing, the hidden allocation

int value = 5;
object boxed = value;        // heap allocation
int unboxed = (int)boxed;    // cast back

Culture aware parsing, essential for decimals

using System.Globalization;

decimal price = decimal.Parse("1,234.56", CultureInfo.InvariantCulture);
DateTime when = DateTime.ParseExact("2026-09-09", "yyyy-MM-dd",
    CultureInfo.InvariantCulture);

Named constants with an underlying integer

enum Status { Draft, Paid, Shipped, Closed }

Status s = Status.Shipped;
Console.WriteLine(s);
Console.WriteLine((int)s);

Explicit values and a different backing type

enum Http : ushort
{
    Ok = 200,
    NotFound = 404,
    ServerError = 500
}

Flags enum for bitwise combinations

[Flags]
enum Access { None = 0, Read = 1, Write = 2, Delete = 4 }

var perms = Access.Read | Access.Write;
bool canWrite = perms.HasFlag(Access.Write);   // true

Parsing and enumerating

Status parsed = Enum.Parse<Status>("Paid");
bool ok = Enum.TryParse("Draft", out Status d);
foreach (Status v in Enum.GetValues<Status>())
    Console.WriteLine(v);

Named tuple, a lightweight multi value

var person = (Name: "Ana", Age: 30);
Console.WriteLine($"{person.Name} is {person.Age}");

Return several values without a class

(int min, int max) Range(int[] xs) => (xs.Min(), xs.Max());

var (lo, hi) = Range(new[] { 4, 9, 1 });

Swap and compare in one expression

(a, b) = (b, a);
bool same = (1, "x") == (1, "x");   // true, element wise

Integer division truncates, watch the types

Console.WriteLine(7 / 2);         // 3
Console.WriteLine(7 % 2);         // 1
Console.WriteLine(7 / 2.0);       // 1.5

Compound assignment and increment

x += 5;  x -= 5;  x *= 2;  x /= 2;  x %= 3;
x++;     // post increment, returns then adds
++x;     // pre increment, adds then returns

Overflow checking is off by default

unchecked { int wrap = int.MaxValue + 1; }   // wraps to min
checked   { int boom = int.MaxValue + 1; }   // OverflowException

Comparison operators return bool

a == b   a != b   a < b   a > b   a <= b   a >= b

Short circuiting versus always evaluating

if (user != null && user.IsActive) { }   // right side skipped if null
bool both = Check(a) & Check(b);         // both always run

Reference equality versus value equality

object x = new string("ab".ToCharArray());
object y = "ab";
Console.WriteLine(x.Equals(y));                  // True
Console.WriteLine(ReferenceEquals(x, y));        // False

Null coalescing and null coalescing assignment

string display = name ?? "anonymous";
cache ??= LoadExpensive();          // assign only when null

Null conditional member, index and invoke

int? len = customer?.Address?.Street?.Length;
string? first = list?[0];
handler?.Invoke(this, EventArgs.Empty);

Null forgiving operator, silences the warning only

string definitely = maybeNull!;   // no runtime check at all

Ternary conditional

string label = count == 1 ? "item" : "items";

Index from end and range slicing

var letters = new[] { 'a', 'b', 'c', 'd', 'e' };
Console.WriteLine(letters[^1]);              // last item
Console.WriteLine(new string(letters[1..4])); // bcd
Console.WriteLine(new string(letters[^3..])); // cde

Ranges are first class values

Range middle = 1..^1;
Index last = ^1;
var slice = numbers[middle];

The full set, on integers

Console.WriteLine(12 & 10);    // AND
Console.WriteLine(12 | 10);    // OR
Console.WriteLine(12 ^ 10);    // XOR
Console.WriteLine(~12);        // NOT
Console.WriteLine(12 << 1);    // left shift
Console.WriteLine(12 >> 2);    // right shift

Unsigned right shift, keeps the sign bit out

int r = -8 >>> 1;   // C# 11

typeof, nameof and sizeof

int count = 0;
Console.WriteLine(typeof(int));
Console.WriteLine(nameof(count));
Console.WriteLine(sizeof(int));

Get the runtime type of an instance

object o = "text";
Console.WriteLine(o.GetType().Name);   // String

nameof survives renames, string literals do not

throw new ArgumentNullException(nameof(order));

Interpolated string, the default choice

string name = "Ana";
int age = 30;
Console.WriteLine($"{name} is {age} years old");

Verbatim string, backslashes stay literal

string path = @"C:\Users\Ana\Documents";
string quoted = @"She said ""hi""";

Raw string literal, no escaping at all

string json = """
    {
      "name": "Ana",
      "path": "C:\Users\Ana"
    }
    """;

Raw plus interpolation, extra dollar signs raise the brace count

string body = $$"""
    { "user": "{{name}}", "css": "{ margin: 0 }" }
    """;

Escape sequences

"\n"  newline      "\t"  tab
"\\"  backslash    "\""  double quote
"\u00e9"  unicode  "\0"  null character

Inspecting

s.Length              s.Contains("ab")
s.StartsWith("A")     s.EndsWith(".cs")
s.IndexOf('x')        s.LastIndexOf('x')
string.IsNullOrEmpty(s)
string.IsNullOrWhiteSpace(s)

Transforming, strings are immutable so each call returns a new one

s.ToUpper()           s.ToLower()
s.Trim()              s.TrimStart()   s.TrimEnd()
s.Replace("a", "b")   s.Insert(0, "x")
s.Substring(2, 5)     s.PadLeft(8, '0')

Split and join

string[] parts = "a,b,c".Split(',');
Console.WriteLine(string.Join("|", parts));

Split with options, drops empty entries and trims

var tags = " a , , b ".Split(',',
    StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
// ["a", "b"]

Comparison that ignores case and culture

bool same = string.Equals(a, b, StringComparison.OrdinalIgnoreCase);
int order = string.Compare(a, b, StringComparison.Ordinal);

Numeric format strings

double v = 1234.5678;
Console.WriteLine(v.ToString("N2"));    // thousands, 2 decimals
Console.WriteLine(v.ToString("C2"));    // currency
Console.WriteLine(0.456.ToString("P2")); // percent

Alignment and format inside interpolation

Console.WriteLine($"{name,-10}|{price,8:F2}");
// left aligned in 10 cols, right aligned in 8 cols

Date and time patterns

DateTime now = DateTime.Now;
now.ToString("yyyy-MM-dd")        // 2026-09-09
now.ToString("HH:mm:ss")          // 14:05:09
now.ToString("dddd, dd MMMM yyyy")
now.ToString("O")                 // round trip ISO 8601

Common numeric specifiers

Build long strings in a loop without allocating each time

using System.Text;

var sb = new StringBuilder();
for (int i = 0; i < 1000; i++)
    sb.AppendLine($"row {i}");

string result = sb.ToString();

Slice without copying, ideal in hot paths

ReadOnlySpan<char> span = "2026-09-09".AsSpan();
ReadOnlySpan<char> year = span[..4];
int y = int.Parse(year);

Create a string in place, no intermediate buffers

string masked = string.Create(11, card, (dst, src) =>
{
    src.AsSpan(0, 4).CopyTo(dst);
    "-****-****".AsSpan().CopyTo(dst[4..]);
});

Match and capture

using System.Text.RegularExpressions;

var rx = new Regex(@"^(\d{4})-(\d{2})-(\d{2})$");
Match m = rx.Match("2026-09-09");
Console.WriteLine(m.Success);
Console.WriteLine(m.Groups[1].Value);

Source generated regex, compiled at build time

public partial class Validators
{
    [GeneratedRegex(@"^[\w.-]+@[\w.-]+\.\w{2,}$", RegexOptions.IgnoreCase)]
    public static partial Regex Email();
}

bool ok = Validators.Email().IsMatch(input);

Replace with a callback

string masked = Regex.Replace(text, @"\d",
    match => "*");

if, else if, else

if (score >= 90)
    grade = "A";
else if (score >= 80)
    grade = "B";
else
    grade = "C";

Guard clause style, fewer nested blocks

if (order is null) return;
if (!order.IsValid) return;

Process(order);

Classic switch statement, break is required

switch (day)
{
    case "Sat":
    case "Sun":
        Console.WriteLine("Weekend");
        break;
    default:
        Console.WriteLine("Weekday");
        break;
}

Switch expression, returns a value and must be exhaustive

string day = "Sat";
string kind = day switch
{
    "Sat" or "Sun" => "Weekend",
    _              => "Weekday"
};
Console.WriteLine(kind);

Guards with when

string band = temp switch
{
    < 0            => "freezing",
    >= 0 and < 15  => "cold",
    >= 15 and < 25 => "mild",
    _              => "hot"
};

for, when you need the index

for (int i = 0; i < 5; i++)
    Console.Write($"{i} ");

foreach, when you only need the item

foreach (var item in collection)
    Console.WriteLine(item);

// with index, C# 8+
foreach (var (item, i) in collection.Select((x, i) => (x, i)))
    Console.WriteLine($"{i}: {item}");

while and do while

while (queue.Count > 0)
    Handle(queue.Dequeue());

do
{
    input = Console.ReadLine();
} while (input != "quit");

Nested loop control

foreach (var row in grid)
{
    foreach (var cell in row)
    {
        if (cell is null) continue;   // next cell
        if (cell.IsStop) goto done;   // break out of both
    }
}
done:
Console.WriteLine("finished");

Infinite loop with an explicit exit

while (true)
{
    var msg = Receive();
    if (msg is null) break;
    Handle(msg);
}

Lazy sequence, values produced on demand

IEnumerable<int> Odds(int max)
{
    for (int i = 1; i <= max; i += 2)
        yield return i;
}

Console.Write(string.Join(" ", Odds(10)));

Stop the sequence early

IEnumerable<string> ReadUntilBlank(TextReader r)
{
    while (true)
    {
        string? line = r.ReadLine();
        if (string.IsNullOrWhiteSpace(line)) yield break;
        yield return line;
    }
}

Test and bind in one step

if (shape is Circle c)
    Console.WriteLine(c.Radius);

Null checks read better as patterns

if (value is null) { }
if (value is not null) { }
if (value is { }) { }        // not null, any shape

Switch over types

double Area(object shape) => shape switch
{
    Circle c    => Math.PI * c.R * c.R,
    Rect r      => r.W * r.H,
    null        => 0,
    _           => throw new ArgumentException("unknown shape")
};

and, or, not combine any two patterns

bool isDigit = ch is >= '0' and <= '9';
bool isVowel = ch is 'a' or 'e' or 'i' or 'o' or 'u';
bool notNull = obj is not null;

Ranges inside a switch expression

int age = 15;
string stage = age switch
{
    < 13          => "child",
    >= 13 and < 20 => "teen",
    _             => "adult"
};
Console.WriteLine(stage);

Match on the shape of an object

if (order is { Status: "paid", Total: > 100 })
    ApplyDiscount(order);

Nested and extended property paths, C# 10

bool local = person is { Address.Country: "RO", Age: >= 18 };

Bind while matching

string Describe(Order o) => o switch
{
    { Items.Count: 0 }                    => "empty",
    { Total: var t } when t > 1000        => $"large order {t:C}",
    { Customer.IsVip: true }              => "vip order",
    _                                     => "standard"
};

Match the shape of a sequence, slice with two dots

int[] xs = { 1, 5, 7, 9 };
string s = xs switch
{
    []                    => "empty",
    [var only]            => $"single {only}",
    [1, .., var last]     => $"starts with 1, ends with {last}",
    _                     => "other"
};
Console.WriteLine(s);

Positional pattern on records and tuples

record Point(int X, int Y);

string Where(Point p) => p switch
{
    (0, 0)              => "origin",
    (var x, 0)          => $"on X at {x}",
    (0, var y)          => $"on Y at {y}",
    _                   => "somewhere"
};

Tuple pattern across two inputs

string Rps(string a, string b) => (a, b) switch
{
    ("rock", "scissors") or ("paper", "rock") => "first wins",
    (var x, var y) when x == y                => "draw",
    _                                          => "second wins"
};

Standard body and expression body

public int Add(int a, int b)
{
    return a + b;
}

public int Multiply(int a, int b) => a * b;
public void Log(string m) => Console.WriteLine(m);

Access modifiers

Overloading, same name, different signature

void Print(int n) { }
void Print(string s) { }
void Print(int n, string unit) { }

Optional and named arguments

void Send(string to, string subject = "(none)", bool urgent = false) { }

Send("a@b.com");
Send("a@b.com", urgent: true);   // skip the middle one

params takes any number of arguments

int Sum(params int[] numbers) => numbers.Sum();

Sum(1, 2, 3);
Sum();               // valid, empty array

ref passes a reference, in and out narrow the intent

void Double(ref int x) => x *= 2;
bool TryGet(string key, out string value) { value = "hit"; return true; }
double Distance(in Point a, in Point b) => 0;   // read only, no copy

int n = 5;
Double(ref n);
Console.WriteLine(n);

params over any collection type, C# 13

void Log(params ReadOnlySpan<string> lines) { }

A helper scoped to one method, can capture locals

int Factorial(int n)
{
    if (n < 0) throw new ArgumentOutOfRangeException(nameof(n));
    return Compute(n);

    static int Compute(int x) => x <= 1 ? 1 : x * Compute(x - 1);
}

static prevents accidental captures and allocations

static bool IsEven(int x) => x % 2 == 0;

Add methods to a type you do not own

public static class StringExtensions
{
    public static bool IsPalindrome(this string s)
    {
        var clean = s.ToLower().Replace(" ", "");
        return clean.SequenceEqual(clean.Reverse());
    }
}

Console.WriteLine("never odd or even".IsPalindrome());

Rules: static class, static method, this on the first parameter

public static IEnumerable<T> WhereNotNull<T>(
    this IEnumerable<T?> source) where T : class
    => source.Where(x => x is not null)!;

Fields, properties, constructor, method

public class BankAccount
{
    private decimal _balance;                  // field
    public string Owner { get; }               // read only property
    public decimal Balance => _balance;        // computed property

    public BankAccount(string owner, decimal opening)
    {
        Owner = owner;
        _balance = opening;
    }

    public void Deposit(decimal amount)
    {
        if (amount <= 0) throw new ArgumentException("must be positive");
        _balance += amount;
    }
}

Creating and using instances

var acc = new BankAccount("Ana", 100m);
acc.Deposit(50m);
Console.WriteLine(acc.Balance);   // 150

Auto property, computed property and full property

public string Name { get; set; } = "";
public string Upper => Name.ToUpper();

private int _age;
public int Age
{
    get => _age;
    set => _age = value >= 0 ? value : throw new ArgumentException();
}

Access levels, init only and required

public string Id { get; private set; }     // settable inside the class
public DateTime Created { get; init; }     // only during construction
public required string Email { get; init; } // caller must supply it

Object and collection initializers

var user = new User
{
    Name = "Ana",
    Email = "ana@example.com",
    Tags = { "admin", "beta" }
};

The field keyword removes the backing field boilerplate, C# 13 preview

public string Slug
{
    get => field;
    set => field = value.Trim().ToLower();
}

Chaining with this and calling a base constructor

public Order() : this(Guid.NewGuid()) { }
public Order(Guid id) { Id = id; }

public PaidOrder(Guid id) : base(id) { }

Primary constructor on a class, parameters are in scope everywhere

public class Greeter(string name, ILogger logger)
{
    public string Hello() => $"Hi {name}";
    public void Warn() => logger.LogWarning("from {Name}", name);
}

Static constructor runs once, before first use

static Config()
{
    Defaults = Load();
}

Static members belong to the type, not an instance

public static class MathHelpers
{
    public static int Counter;
    public static int Square(int x) => x * x;
}

MathHelpers.Square(4);

Indexer, make your type usable with square brackets

public class Grid
{
    private readonly int[,] _cells = new int[8, 8];
    public int this[int row, int col]
    {
        get => _cells[row, col];
        set => _cells[row, col] = value;
    }
}

var g = new Grid();
g[0, 0] = 1;

Deconstruct, so your type supports tuple assignment

public void Deconstruct(out string name, out int age)
{
    name = Name;
    age = Age;
}

var (n, a) = person;

Partial class, split one type across files

// Order.cs
public partial class Order { public Guid Id { get; set; } }
// Order.Validation.cs
public partial class Order { public bool IsValid() => Id != Guid.Empty; }

One line gives you equality, ToString and deconstruction

public record Person(string FirstName, string LastName);

var a = new Person("Ana", "Pop");
var b = new Person("Ana", "Pop");
Console.WriteLine(a == b);
Console.WriteLine(a);

with expression makes a modified copy

var married = a with { LastName = "Ionescu" };
// a is untouched

Add members like any class

public record Order(Guid Id, decimal Total)
{
    public bool IsLarge => Total > 1000m;
    public static Order Empty { get; } = new(Guid.Empty, 0m);
}

Record struct, value type with value equality

public readonly record struct Money(decimal Amount, string Currency);

Records inherit, and equality includes the runtime type

public record Animal(string Name);
public record Dog(string Name, string Breed) : Animal(Name);

A value type, copied on assignment

public readonly struct Point
{
    public int X { get; }
    public int Y { get; }
    public Point(int x, int y) => (X, Y) = (x, y);
    public override string ToString() => $"({X}, {Y})";
}

ref struct lives on the stack only, Span is one

public ref struct Buffer
{
    private Span<byte> _data;   // cannot be boxed or captured
}

When to reach for a struct

// small (roughly 16 bytes or less)
// immutable
// short lived and allocated in large numbers
// otherwise use a class or a record

virtual in the base, override in the child

public class Animal
{
    public virtual string Speak() => "...";
}

public class Dog : Animal
{
    public override string Speak() => "Woof";
}

Animal a = new Dog();
Console.WriteLine(a.Speak());

Call the base implementation

public override string Speak() => base.Speak() + " Woof";

abstract cannot be instantiated, sealed cannot be extended

public abstract class Shape
{
    public abstract double Area();          // no body, must be overridden
    public virtual string Describe() => $"area {Area():F2}";
}

public sealed class Circle : Shape
{
    public double R { get; init; }
    public override double Area() => Math.PI * R * R;
}

new hides instead of overriding, usually a mistake

public new string Speak() => "hidden";   // base reference calls the base version

A contract, a type can implement many

public interface IRepository<T>
{
    Task<T?> GetAsync(Guid id);
    Task SaveAsync(T item);
}

public class OrderRepo : IRepository<Order>, IDisposable
{
    public Task<Order?> GetAsync(Guid id) => Task.FromResult<Order?>(null);
    public Task SaveAsync(Order item) => Task.CompletedTask;
    public void Dispose() { }
}

Default implementation, so adding a member is not a breaking change

public interface ILogger
{
    void Log(string message);
    void LogError(string message) => Log($"ERROR: {message}");
}

Explicit implementation hides the member from the class surface

void IDisposable.Dispose() { }
// only reachable through an IDisposable reference

Static abstract members, generic math

public interface IAddable<T> where T : IAddable<T>
{
    static abstract T Zero { get; }
    static abstract T operator +(T a, T b);
}

Override ToString, Equals and GetHashCode together

public override string ToString() => $"{Name} ({Id})";

public override bool Equals(object? obj) =>
    obj is User u && u.Id == Id;

public override int GetHashCode() => Id.GetHashCode();

Operator overloading, always in pairs

public static Money operator +(Money a, Money b) =>
    new(a.Amount + b.Amount, a.Currency);

public static bool operator ==(Money a, Money b) => a.Equals(b);
public static bool operator !=(Money a, Money b) => !a.Equals(b);

Custom conversions

public static implicit operator decimal(Money m) => m.Amount;
public static explicit operator Money(decimal d) => new(d, "EUR");

IComparable makes your type sortable

public int CompareTo(Money? other) =>
    Amount.CompareTo(other?.Amount ?? 0);

One implementation, many types, no boxing

public class Box<T>
{
    public T? Value { get; set; }
    public bool HasValue => Value is not null;
}

var b = new Box<int> { Value = 42 };

Generic method, the type is usually inferred

T FirstOrDefaultSafe<T>(IEnumerable<T> xs, T fallback) =>
    xs.Any() ? xs.First() : fallback;

int n = FirstOrDefaultSafe(numbers, -1);   // T inferred as int

Multiple type parameters

public class Cache<TKey, TValue> where TKey : notnull
{
    private readonly Dictionary<TKey, TValue> _map = new();
}

The full list

Combining constraints, order matters

public T Create<T>() where T : class, IEntity, new()
{
    var item = new T();
    item.Id = Guid.NewGuid();
    return item;
}

Generic math over any number type, C# 11

using System.Numerics;

T Sum<T>(IEnumerable<T> xs) where T : INumber<T>
{
    T total = T.Zero;
    foreach (var x in xs) total += x;
    return total;
}

Variance, out for producers and in for consumers

IEnumerable<object> objects = new List<string>();  // covariant, out T

Action<object> printAny = o => Console.WriteLine(o);
Action<string> printText = printAny;               // contravariant, in T

Declaring, fixed length once created

int[] a = new int[5];              // zero filled
int[] b = { 1, 2, 3 };
int[] c = new[] { 1, 2, 3 };
int[] d = [1, 2, 3];               // collection expression, C# 12

Multidimensional versus jagged

int[,] grid = new int[3, 4];       // rectangular
grid[1, 2] = 9;

int[][] rows = new int[3][];       // jagged, rows can differ
rows[0] = new int[] { 1, 2 };

Useful array operations

Array.Sort(a);
Array.Reverse(a);
Array.IndexOf(a, 3);
Array.Fill(a, 7);
int[] copy = (int[])a.Clone();
Array.Copy(a, copy, a.Length);

The default resizable collection

var list = new List<string> { "a", "b" };
list.Add("c");
list.Insert(0, "z");
list.Remove("z");
Console.WriteLine(list.Count);
Console.WriteLine(list[1]);

Searching and bulk operations

list.Contains("a");
list.IndexOf("b");
list.Find(s => s.StartsWith("a"));
list.RemoveAll(s => s.Length > 3);
list.AddRange(other);
list.Sort();
list.Clear();

Preallocate the capacity when you know the size

var big = new List<int>(capacity: 10_000);

Key to value lookup, average O(1)

var ages = new Dictionary<string, int>
{
    ["Ana"] = 1,
    ["Luca"] = 2
};

Console.WriteLine(ages["Ana"]);
Console.WriteLine($"{ages.TryGetValue("Luca", out int v)} {v}");

Safe add, update and remove

ages.TryAdd("Mira", 3);          // false if present, never throws
ages["Ana"] = 10;                // add or overwrite
ages.Remove("Luca");
ages.ContainsKey("Ana");

Iterate keys, values or pairs

foreach (var (name, age) in ages)
    Console.WriteLine($"{name}: {age}");

foreach (string k in ages.Keys) { }
foreach (int val in ages.Values) { }

Case insensitive keys and counting patterns

var map = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);

foreach (var word in words)
    map[word] = map.GetValueOrDefault(word) + 1;

HashSet holds unique values

var set = new HashSet<int> { 1, 2, 2 };
set.Add(2);                  // false, already there
Console.WriteLine(set.Count);

Set algebra in place

a.UnionWith(b);
a.IntersectWith(b);
a.ExceptWith(b);
bool sub = a.IsSubsetOf(b);

Queue is first in first out, Stack is last in first out

var q = new Queue<string>();
q.Enqueue("first"); q.Enqueue("second");
q.Dequeue();                 // "first"

var st = new Stack<string>();
st.Push("bottom"); st.Push("top");
st.Pop();                    // "top"

PriorityQueue, .NET 6 and later

var pq = new PriorityQueue<string, int>();
pq.Enqueue("low", 5);
pq.Enqueue("urgent", 1);
pq.Dequeue();                // "urgent", lowest priority value wins

One syntax for arrays, lists and spans

int[] a         = [1, 2, 3];
List<int> b     = [1, 2, 3];
Span<int> c     = [1, 2, 3];
ImmutableArray<int> d = [1, 2, 3];

Spread another collection with two dots

int[] head = [1, 2];
int[] tail = [4, 5];
int[] all = [..head, 3, ..tail];
Console.Write(string.Join(" ", all));

Immutable collections return a new instance on change

using System.Collections.Immutable;

var list = ImmutableList.Create(1, 2, 3);
var bigger = list.Add(4);     // list still has 3 items

Thread safe collections, no external lock needed

using System.Collections.Concurrent;

var cache = new ConcurrentDictionary<string, int>();
cache.AddOrUpdate("hits", 1, (_, old) => old + 1);
int v = cache.GetOrAdd("misses", _ => 0);

var bag = new ConcurrentBag<string>();
var queue = new BlockingCollection<string>();

Read only views, cheap and safe to hand out

IReadOnlyList<int> view = list.AsReadOnly();
ReadOnlyDictionary<string, int> ro = new(map);

Method syntax is the one you will see most

var names = people
    .Where(p => p.Age >= 18)
    .OrderBy(p => p.LastName)
    .Select(p => p.FirstName)
    .ToList();

Query syntax reads well for joins and groups

var names = from p in people
            where p.Age >= 18
            orderby p.LastName
            select p.FirstName;

Queries are lazy until you materialise them

var q = numbers.Where(n => n > 10);   // nothing has run yet
var list = q.ToList();                // now it runs
// ToArray, ToList, ToDictionary, ToHashSet, Count, First all force execution

Where filters, Select transforms

int[] xs = [1, 2, 3, 4, 5, 6];
var evenSquares = xs.Where(x => x % 2 == 0).Select(x => x * x);
Console.Write(string.Join(" ", evenSquares));

SelectMany flattens nested sequences

var allTags = posts.SelectMany(p => p.Tags).Distinct();

Project into an anonymous type or a record

var rows = orders.Select(o => new { o.Id, o.Total, Year = o.Date.Year });
var dtos = orders.Select(o => new OrderDto(o.Id, o.Total));

Where with the index

var everyOther = xs.Where((x, i) => i % 2 == 0);

Sort by one key then another

var sorted = people
    .OrderBy(p => p.LastName)
    .ThenByDescending(p => p.Age);

Paging with Skip and Take

int page = 3, size = 20;
var slice = query.Skip((page - 1) * size).Take(size);

Set operations across sequences

a.Distinct()          a.Union(b)
a.Intersect(b)        a.Except(b)
a.Concat(b)           a.SequenceEqual(b)

Key based variants, .NET 6 and later

var unique = people.DistinctBy(p => p.Email);
var top = people.MaxBy(p => p.Score);
var chunks = people.Chunk(100);       // batches of 100

GroupBy returns a sequence of groups with a Key

var byCity = people.GroupBy(p => p.City);

foreach (var group in byCity)
    Console.WriteLine($"{group.Key}: {group.Count()}");

Group and aggregate in one pass

var stats = orders
    .GroupBy(o => o.CustomerId)
    .Select(g => new
    {
        Customer = g.Key,
        Orders = g.Count(),
        Revenue = g.Sum(o => o.Total)
    })
    .OrderByDescending(x => x.Revenue);

Inner join on a shared key

var rows = orders.Join(
    customers,
    o => o.CustomerId,
    c => c.Id,
    (o, c) => new { c.Name, o.Total });

Left join through GroupJoin and DefaultIfEmpty

var left = from c in customers
           join o in orders on c.Id equals o.CustomerId into g
           from o in g.DefaultIfEmpty()
           select new { c.Name, Total = o?.Total ?? 0 };

ToLookup builds a reusable one to many index

var index = orders.ToLookup(o => o.CustomerId);
var mine = index[customerId];   // empty sequence if the key is missing

The common aggregates

int[] xs = [1, 2, 3, 4, 5, 6];
Console.WriteLine(xs.Sum());
Console.WriteLine(xs.Average());
Console.WriteLine(xs.Max());
Console.WriteLine(xs.Min());

First, Single and their safe variants

xs.First();                  // throws if empty
xs.FirstOrDefault();         // 0 or null
xs.FirstOrDefault(-1);       // custom default, .NET 6+
xs.Single(x => x > 5);       // throws if not exactly one match
xs.SingleOrDefault();
xs.Last();  xs.ElementAtOrDefault(2);

Quantifiers and counting

bool anyAdults = people.Any(p => p.Age >= 18);
bool allValid  = orders.All(o => o.IsValid);
bool hasItems  = list.Any();          // cheaper than Count() > 0
int adults     = people.Count(p => p.Age >= 18);

Aggregate folds a sequence into one value

string csv = names.Aggregate((acc, n) => $"{acc}, {n}");
int product = xs.Aggregate(1, (acc, x) => acc * x);

Generators and pairing

Enumerable.Range(1, 10);
Enumerable.Repeat("x", 3);
Enumerable.Empty<int>();
names.Zip(scores, (n, s) => $"{n}: {s}");

Expression lambda and statement lambda

Func<int, int> square = x => x * x;

Func<int, string> describe = x =>
{
    if (x < 0) return "negative";
    return x.ToString();
};

Console.WriteLine(square(5));

Explicit types, defaults and params, C# 12

var add = (int a, int b = 10) => a + b;
var log = (params string[] parts) => string.Join(" ", parts);

Closures capture variables, not values

int factor = 2;
Func<int, int> scale = x => x * factor;
factor = 10;
Console.WriteLine(scale(5));    // 50, not 10

static lambda refuses to capture, which avoids allocations

Func<int, int> pure = static x => x * 2;

Built in delegate types, no custom declaration needed

Func<int, int, int> add = (a, b) => a + b;   // last parameter is the return
Action<string> print = s => Console.WriteLine(s);  // returns void
Predicate<int> isEven = n => n % 2 == 0;     // returns bool

Pass behaviour into a method

void Retry(int times, Action work)
{
    for (int i = 0; i < times; i++)
    {
        try { work(); return; }
        catch when (i < times - 1) { }
    }
}

Retry(3, () => CallApi());

Custom delegate and multicast invocation

public delegate void Notify(string message);

Notify chain = m => Console.WriteLine($"log: {m}");
chain += m => File.AppendAllText("app.log", m);
chain("started");         // both run, in order

Method group, shorter than a lambda that just forwards

names.ForEach(Console.WriteLine);     // instead of x => Console.WriteLine(x)

Declare, raise and subscribe

public class Downloader
{
    public event EventHandler<int>? ProgressChanged;

    private void Report(int percent) =>
        ProgressChanged?.Invoke(this, percent);
}

var d = new Downloader();
d.ProgressChanged += (sender, pct) => Console.WriteLine($"{pct}%");

Custom event arguments

public class FileFoundEventArgs : EventArgs
{
    public required string Path { get; init; }
}

public event EventHandler<FileFoundEventArgs>? FileFound;

Always unsubscribe, otherwise the publisher keeps the subscriber alive

d.ProgressChanged -= Handler;

Await releases the thread while the work is pending

public async Task<string> GetTitleAsync(string url)
{
    using var http = new HttpClient();
    string html = await http.GetStringAsync(url);
    return html[..50];
}

Return types

Async all the way down, never block with .Result or .Wait()

// wrong, can deadlock
string s = GetTitleAsync(url).Result;

// right
string s = await GetTitleAsync(url);

Already finished results, without an await

Task.CompletedTask;
Task.FromResult(42);
ValueTask.FromResult(42);
Task.FromException(new IOException());

Start together, then await together

Task<string> a = GetAsync(url1);
Task<string> b = GetAsync(url2);

string[] both = await Task.WhenAll(a, b);

First one to finish wins

Task done = await Task.WhenAny(primary, fallback);
string result = await (Task<string>)done;

Fan out over a collection

var results = await Task.WhenAll(urls.Select(GetAsync));

Bounded concurrency, .NET 6 and later

await Parallel.ForEachAsync(urls,
    new ParallelOptions { MaxDegreeOfParallelism = 4 },
    async (url, ct) => await DownloadAsync(url, ct));

CPU bound work belongs on a background thread

int result = await Task.Run(() => HeavyComputation());

Pass the token down the whole call chain

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

try
{
    await LongRunningAsync(cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("timed out");
}

Check the token inside your own loops

foreach (var item in items)
{
    ct.ThrowIfCancellationRequested();
    await ProcessAsync(item, ct);
}

Combine several tokens into one

using var linked = CancellationTokenSource
    .CreateLinkedTokenSource(userToken, shutdownToken);

Add a timeout to any task, .NET 8 and later

await slowTask.WaitAsync(TimeSpan.FromSeconds(2));

Yield results as they arrive

async IAsyncEnumerable<string> ReadLinesAsync(
    string path, [EnumeratorCancellation] CancellationToken ct = default)
{
    using var reader = new StreamReader(path);
    while (await reader.ReadLineAsync(ct) is { } line)
        yield return line;
}

await foreach (string line in ReadLinesAsync("log.txt"))
    Console.WriteLine(line);

lock protects shared state on synchronous paths

private readonly object _gate = new();

lock (_gate)
{
    _counter++;
}
// never await inside a lock

SemaphoreSlim is the async friendly gate

private readonly SemaphoreSlim _slots = new(1, 1);

await _slots.WaitAsync(ct);
try { await MutateAsync(); }
finally { _slots.Release(); }

Atomic counters without a lock

Interlocked.Increment(ref _count);
Interlocked.Exchange(ref _flag, 1);
Interlocked.CompareExchange(ref _state, newValue, expected);

ConfigureAwait(false) in library code, skips the captured context

var data = await client.GetAsync(url).ConfigureAwait(false);

Catch the specific type first, the general one last

try
{
    string text = File.ReadAllText(path);
}
catch (FileNotFoundException ex)
{
    Console.WriteLine($"missing: {ex.FileName}");
}
catch (IOException ex)
{
    Console.WriteLine(ex.Message);
}
finally
{
    Console.WriteLine("always runs");
}

Exception filter with when, the stack is not unwound if it is false

catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
{
    return null;
}

Rethrow, keep the original stack trace

catch (Exception ex)
{
    Log(ex);
    throw;            // correct
    // throw ex;      // wrong, resets the stack trace
}

Wrap with context, keep the inner exception

throw new InvalidOperationException("Could not import the order", ex);

Common built in exceptions

Your own exception type

public class OrderNotFoundException : Exception
{
    public Guid OrderId { get; }

    public OrderNotFoundException(Guid id)
        : base($"Order {id} was not found")
        => OrderId = id;
}

throw as an expression

string name = input ?? throw new ArgumentNullException(nameof(input));
int code = status switch { "ok" => 200, _ => throw new ArgumentException() };

Deterministic cleanup, even when an exception is thrown

using (var stream = File.OpenRead(path))
{
    // stream.Dispose() runs at the closing brace
}

// declaration form, disposed at the end of the scope
using var reader = new StreamReader(path);

Async disposal

await using var conn = new SqlConnection(cs);
await conn.OpenAsync(ct);

Implement it on your own type

public sealed class Session : IDisposable
{
    private bool _disposed;

    public void Dispose()
    {
        if (_disposed) return;
        _handle.Close();
        _disposed = true;
    }
}

Whole file helpers, sync and async

string text = File.ReadAllText(path);
string[] lines = File.ReadAllLines(path);
byte[] bytes = File.ReadAllBytes(path);

await File.WriteAllTextAsync(path, text);
await File.AppendAllTextAsync(path, "\nmore");

Existence, copy, move, delete

File.Exists(path);
File.Copy(src, dst, overwrite: true);
File.Move(src, dst);
File.Delete(path);

Paths, always compose them with Path

string full = Path.Combine(root, "logs", "app.log");
string ext = Path.GetExtension(full);          // .log
string name = Path.GetFileNameWithoutExtension(full);
string dir = Path.GetDirectoryName(full)!;
string temp = Path.GetTempFileName();

Directories and enumeration

Directory.CreateDirectory(dir);
foreach (string f in Directory.EnumerateFiles(dir, "*.cs",
             SearchOption.AllDirectories))
    Console.WriteLine(f);

Stream a large file line by line, low memory

using var reader = new StreamReader(path);
while (await reader.ReadLineAsync() is { } line)
    Process(line);

Serialize and deserialize

using System.Text.Json;

var person = new { Name = "Ana", Age = 30 };
string json = JsonSerializer.Serialize(person);
Console.WriteLine(json);

var back = JsonSerializer.Deserialize<Person>(json);

Options you will almost always want

var opts = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    PropertyNameCaseInsensitive = true,
    WriteIndented = true,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

Attributes on the model

public class Product
{
    [JsonPropertyName("product_id")] public int Id { get; set; }
    [JsonIgnore] public string? Internal { get; set; }
}

Stream straight to and from a file

await using var fs = File.Create(path);
await JsonSerializer.SerializeAsync(fs, data, opts);

Prefer DateTimeOffset or the date only types

DateTime now = DateTime.Now;             // local, ambiguous
DateTime utc = DateTime.UtcNow;          // store this
DateTimeOffset off = DateTimeOffset.Now; // carries the offset
DateOnly day = DateOnly.FromDateTime(now);
TimeOnly clock = TimeOnly.FromDateTime(now);

Arithmetic and differences

DateTime tomorrow = now.AddDays(1);
TimeSpan age = now - birthday;
Console.WriteLine(age.TotalDays);
TimeSpan half = TimeSpan.FromMinutes(30);

Time zones and testable clocks

var tz = TimeZoneInfo.FindSystemTimeZoneById("Europe/Bucharest");
var local = TimeZoneInfo.ConvertTime(utc, tz);

TimeProvider clock = TimeProvider.System;   // inject this, .NET 8+
DateTimeOffset nowTestable = clock.GetUtcNow();

Identifiers

Guid id = Guid.NewGuid();
string text = id.ToString("N");        // no dashes
bool ok = Guid.TryParse(input, out Guid parsed);
Guid v7 = Guid.CreateVersion7();       // time ordered, .NET 9

Random numbers, use the shared instance

int roll = Random.Shared.Next(1, 7);       // 1 to 6
double unit = Random.Shared.NextDouble();  // 0.0 to 1.0
Random.Shared.Shuffle(items);              // .NET 8

var seeded = new Random(42);               // reproducible in tests

Cryptographically secure randomness

using System.Security.Cryptography;

int secure = RandomNumberGenerator.GetInt32(1, 7);
byte[] key = RandomNumberGenerator.GetBytes(32);
string token = Convert.ToHexString(key);

Environment and process information

Environment.GetEnvironmentVariable("PATH");
Environment.CurrentDirectory;
Environment.ProcessorCount;
Environment.NewLine;
Environment.Exit(1);
Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);

Rounding, and the banker's rounding surprise

Console.WriteLine(Math.Round(3.5));                 // 4
Console.WriteLine(Math.Round(2.5));                 // 3 when away from zero
Console.WriteLine(Math.Floor(-2.1));                // -3
Console.WriteLine(Math.Ceiling(4.1));               // 5
Console.WriteLine(Math.Clamp(15, 0, 10));           // 10

Control the midpoint rule explicitly

Math.Round(2.5);                                  // 2, to even
Math.Round(2.5, MidpointRounding.AwayFromZero);   // 3
Math.Round(3.14159, 2);                           // 3.14

Common operations

Math.Abs(-7)        Math.Max(a, b)     Math.Min(a, b)
Math.Pow(2, 10)     Math.Sqrt(144)     Math.Cbrt(27)
Math.Log(e)         Math.Log10(1000)   Math.Sign(-4)
Math.DivRem(17, 5, out int rem)

Floating point comparison

// wrong
if (0.1 + 0.2 == 0.3) { }              // false

// right
if (Math.Abs((0.1 + 0.2) - 0.3) < 1e-9) { }
// or use decimal for money
if (0.1m + 0.2m == 0.3m) { }           // true

Measure elapsed time

using System.Diagnostics;

var sw = Stopwatch.StartNew();
DoWork();
sw.Stop();
Console.WriteLine($"took {sw.ElapsedMilliseconds} ms");

// allocation free, .NET 7+
long start = Stopwatch.GetTimestamp();
TimeSpan spent = Stopwatch.GetElapsedTime(start);

Debug and trace output

Debug.WriteLine("only in debug builds");
Debug.Assert(count > 0, "count must be positive");
Trace.WriteLine("in debug and release");

Run an external process

var info = new ProcessStartInfo("git", "status")
{
    RedirectStandardOutput = true,
    UseShellExecute = false
};
using var proc = Process.Start(info)!;
string output = await proc.StandardOutput.ReadToEndAsync();
await proc.WaitForExitAsync();

GET and deserialize in one call

using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.example.com/") };
var user = await http.GetFromJsonAsync<User>("users/1", ct);

POST with a JSON body and check the status

HttpResponseMessage res = await http.PostAsJsonAsync("orders", newOrder, ct);
res.EnsureSuccessStatusCode();
var created = await res.Content.ReadFromJsonAsync<Order>(cancellationToken: ct);

Never create one per request

// in Program.cs
builder.Services.AddHttpClient<GitHubClient>(c =>
{
    c.BaseAddress = new Uri("https://api.github.com/");
    c.DefaultRequestHeaders.Add("User-Agent", "my-app");
});

// then inject HttpClient into GitHubClient

Headers, timeouts and cancellation

http.Timeout = TimeSpan.FromSeconds(10);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var res = await http.GetAsync("slow", cts.Token);

Interface to implementation, in Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<IClock, SystemClock>();
builder.Services.AddScoped<IOrderRepository, OrderRepository>();
builder.Services.AddTransient<IEmailSender, SmtpSender>();

The three lifetimes

Factory registration and instance registration

builder.Services.AddSingleton<IClock>(_ => new FixedClock(DateTime.UtcNow));
builder.Services.AddSingleton(new AppInfo("api", "1.4.0"));
builder.Services.TryAddScoped<ICache, MemoryCache>();   // skip if present

Catch lifetime mistakes at startup, not in production

builder.Host.UseDefaultServiceProvider(o =>
{
    o.ValidateScopes = true;
    o.ValidateOnBuild = true;
});

Constructor injection, the default and the one to reach for

public class OrderService(
    IOrderRepository repo,
    ILogger<OrderService> logger)
{
    public async Task<Order?> GetAsync(Guid id)
    {
        logger.LogInformation("Loading order {OrderId}", id);
        return await repo.GetAsync(id);
    }
}

Resolve a scoped service inside a singleton or a background job

public class Worker(IServiceScopeFactory scopes) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        using IServiceScope scope = scopes.CreateScope();
        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        await db.SaveChangesAsync(ct);
    }
}

Get versus GetRequired

var maybe = provider.GetService<IThing>();          // null if unregistered
var must  = provider.GetRequiredService<IThing>();  // throws if unregistered
var many  = provider.GetServices<IHandler>();       // every registration

appsettings.json and per environment overrides

{
  "ConnectionStrings": { "Default": "Server=.;Database=Shop" },
  "Smtp": { "Host": "mail.example.com", "Port": 587 }
}
// appsettings.Development.json overrides matching keys

Read a value, with a section path

string cs = builder.Configuration.GetConnectionString("Default")!;
int port = builder.Configuration.GetValue<int>("Smtp:Port");
IConfigurationSection smtp = builder.Configuration.GetSection("Smtp");

Bind a section to a typed class

public class SmtpOptions
{
    public required string Host { get; set; }
    public int Port { get; set; } = 25;
}

builder.Services.Configure<SmtpOptions>(
    builder.Configuration.GetSection("Smtp"));

// then inject IOptions<SmtpOptions> and read .Value

Validate options at startup

builder.Services.AddOptions<SmtpOptions>()
    .Bind(builder.Configuration.GetSection("Smtp"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

Secrets stay out of source control

dotnet user-secrets init
dotnet user-secrets set "Smtp:Password" "hunter2"

# environment variables use a double underscore for nesting
export Smtp__Password=hunter2

Structured logging, keep the placeholders

logger.LogInformation("Loading order {OrderId} for {Customer}", id, name);

// not this, the values become unsearchable
logger.LogInformation($"Loading order {id} for {name}");

Levels, from most to least verbose

logger.LogTrace("...");        // step by step detail
logger.LogDebug("...");        // developer diagnostics
logger.LogInformation("...");  // normal flow
logger.LogWarning("...");      // unexpected but handled
logger.LogError(ex, "...");    // the operation failed
logger.LogCritical(ex, "..."); // the app cannot continue

Always pass the exception as the first argument

catch (Exception ex)
{
    logger.LogError(ex, "Import failed for {File}", path);
    throw;
}

Scopes attach context to everything inside

using (logger.BeginScope("Order {OrderId}", id))
{
    logger.LogInformation("validated");   // carries OrderId
    logger.LogInformation("charged");     // carries OrderId
}

Compile time logging, no boxing and no allocation

public static partial class Log
{
    [LoggerMessage(Level = LogLevel.Warning,
        Message = "Retry {Attempt} for {Url}")]
    public static partial void Retry(ILogger logger, int attempt, string url);
}

A console app with DI, config and logging

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHostedService<Worker>();
builder.Services.AddSingleton<IClock, SystemClock>();

IHost host = builder.Build();
await host.RunAsync();

A long running background service

public class Worker(ILogger<Worker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            logger.LogInformation("tick at {Now}", DateTimeOffset.UtcNow);
            await Task.Delay(TimeSpan.FromSeconds(30), ct);
        }
    }
}

A complete working API in one file

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IOrderRepository, OrderRepository>();

var app = builder.Build();

app.MapGet("/orders/{id:guid}", async (Guid id, IOrderRepository repo) =>
    await repo.GetAsync(id) is { } order
        ? Results.Ok(order)
        : Results.NotFound());

app.MapPost("/orders", async (Order order, IOrderRepository repo) =>
{
    await repo.SaveAsync(order);
    return Results.Created($"/orders/{order.Id}", order);
});

app.Run();

Every verb, plus route groups

app.MapGet("/health", () => "ok");
app.MapPut("/orders/{id:guid}", Update);
app.MapDelete("/orders/{id:guid}", Delete);
app.MapPatch("/orders/{id:guid}", Patch);

var orders = app.MapGroup("/orders").RequireAuthorization();
orders.MapGet("/", ListAll);

Route constraints

"/users/{id:int}"          "/items/{id:guid}"
"/posts/{slug:alpha}"      "/page/{n:min(1)}"
"/files/{name:length(1,64)}"
"/archive/{year:int:range(1990,2100)}"
"/optional/{tag?}"

Where each parameter comes from

app.MapGet("/search", (
    [FromRoute] int id,
    [FromQuery] string? q,
    [FromHeader(Name = "X-Tenant")] string tenant,
    [FromServices] ISearchService svc,
    CancellationToken ct) => svc.FindAsync(q, ct));

// simple types default to the query string,
// complex types default to the JSON body

Returning the right status code

Results.Ok(value)                Results.NoContent()
Results.Created(uri, value)      Results.Accepted()
Results.NotFound()               Results.BadRequest(problem)
Results.Conflict()               Results.Unauthorized()
Results.Forbid()                 Results.File(bytes, "application/pdf")
Results.Problem("Payment declined", statusCode: 402)

TypedResults documents the response for OpenAPI

app.MapGet("/orders/{id:guid}",
    async Task<Results<Ok<Order>, NotFound>> (Guid id, IOrderRepository repo)
        => await repo.GetAsync(id) is { } o
            ? TypedResults.Ok(o)
            : TypedResults.NotFound());

Model validation with data annotations

public record CreateOrder(
    [Required, StringLength(80)] string Customer,
    [Range(1, 999)] int Quantity,
    [EmailAddress] string Email);

The MVC style, still the default for larger APIs

[ApiController]
[Route("api/[controller]")]
public class OrdersController(IOrderRepository repo) : ControllerBase
{
    [HttpGet("{id:guid}")]
    public async Task<ActionResult<Order>> Get(Guid id)
    {
        Order? order = await repo.GetAsync(id);
        return order is null ? NotFound() : Ok(order);
    }

    [HttpPost]
    public async Task<ActionResult<Order>> Create([FromBody] Order order)
    {
        await repo.SaveAsync(order);
        return CreatedAtAction(nameof(Get), new { id = order.Id }, order);
    }
}

Wire controllers into the pipeline

builder.Services.AddControllers();
// ...
app.MapControllers();

ApiController gives you automatic 400 responses

// with [ApiController], invalid ModelState returns
// a ProblemDetails 400 before your action runs.
// to turn it off:
builder.Services.Configure<ApiBehaviorOptions>(o =>
    o.SuppressModelStateInvalidFilter = true);

A named CORS policy

builder.Services.AddCors(o => o.AddPolicy("frontend", p =>
    p.WithOrigins("https://app.example.com")
     .AllowAnyHeader()
     .AllowAnyMethod()));

app.UseCors("frontend");

JWT bearer authentication

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o => o.Authority = "https://login.example.com");

builder.Services.AddAuthorization(o =>
    o.AddPolicy("admin", p => p.RequireRole("Admin")));

app.MapGet("/secret", () => "shh").RequireAuthorization("admin");

Read the signed in user

string? id = User.FindFirstValue(ClaimTypes.NameIdentifier);
bool isAdmin = User.IsInRole("Admin");

OpenAPI document, built in from .NET 9

builder.Services.AddOpenApi();
// ...
app.MapOpenApi();   // served at /openapi/v1.json

Define the context and its sets

public class ShopContext(DbContextOptions<ShopContext> options)
    : DbContext(options)
{
    public DbSet<Order> Orders => Set<Order>();
    public DbSet<Customer> Customers => Set<Customer>();
}

Register it, scoped by default

builder.Services.AddDbContext<ShopContext>(o =>
    o.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

// UseNpgsql, UseSqlite, UseCosmos, UseInMemoryDatabase

An entity

public class Order
{
    public Guid Id { get; set; }
    public required string Reference { get; set; }
    public decimal Total { get; set; }
    public DateTime PlacedAt { get; set; }

    public Guid CustomerId { get; set; }
    public Customer Customer { get; set; } = null!;
    public List<OrderLine> Lines { get; set; } = [];
}

Reading single rows

Order? byKey = await db.Orders.FindAsync(id);          // checks the cache first
Order? first = await db.Orders.FirstOrDefaultAsync(o => o.Total > 100, ct);
Order one    = await db.Orders.SingleAsync(o => o.Reference == code, ct);

Loading related data

var orders = await db.Orders
    .Include(o => o.Customer)
    .Include(o => o.Lines)
        .ThenInclude(l => l.Product)
    .ToListAsync(ct);

Project to exactly the columns you need

var rows = await db.Orders
    .Where(o => o.PlacedAt >= from)
    .OrderByDescending(o => o.PlacedAt)
    .Select(o => new OrderSummary(o.Id, o.Reference, o.Customer.Name, o.Total))
    .Take(50)
    .ToListAsync(ct);

Turn off tracking for read only queries

var report = await db.Orders
    .AsNoTracking()
    .Where(o => o.Total > 1000)
    .ToListAsync(ct);

Paging and aggregates run in SQL

var page = await db.Orders.OrderBy(o => o.Id)
    .Skip((n - 1) * size).Take(size).ToListAsync(ct);

int count = await db.Orders.CountAsync(o => o.Total > 100, ct);
decimal sum = await db.Orders.SumAsync(o => o.Total, ct);
bool any = await db.Orders.AnyAsync(o => o.Reference == code, ct);

Raw SQL when LINQ is not enough

var rows = await db.Orders
    .FromSql($"SELECT * FROM Orders WHERE Total > {threshold}")
    .ToListAsync(ct);
// interpolation here is parameterised, not concatenated

Insert, update, delete

db.Orders.Add(order);
db.Orders.AddRange(batch);

Order existing = await db.Orders.FindAsync(id);
existing.Total = 99m;              // tracked, no Update call needed

db.Orders.Remove(existing);

await db.SaveChangesAsync(ct);     // one transaction

Bulk update and delete without loading rows

await db.Orders
    .Where(o => o.PlacedAt < cutoff)
    .ExecuteDeleteAsync(ct);                       // EF 7+

await db.Orders
    .Where(o => o.Status == "pending")
    .ExecuteUpdateAsync(s => s.SetProperty(o => o.Status, "expired"), ct);

Explicit transactions across several saves

await using var tx = await db.Database.BeginTransactionAsync(ct);
try
{
    await db.SaveChangesAsync(ct);
    await other.SaveChangesAsync(ct);
    await tx.CommitAsync(ct);
}
catch
{
    await tx.RollbackAsync(ct);
    throw;
}

Handle a concurrency conflict

try { await db.SaveChangesAsync(ct); }
catch (DbUpdateConcurrencyException ex)
{
    foreach (var entry in ex.Entries)
        await entry.ReloadAsync(ct);
}

The commands you will run most

dotnet tool install --global dotnet-ef
dotnet ef migrations add AddOrderStatus
dotnet ef database update
dotnet ef migrations remove
dotnet ef migrations script --idempotent -o deploy.sql
dotnet ef dbcontext scaffold "..." Microsoft.EntityFrameworkCore.SqlServer

Fluent configuration

protected override void OnModelCreating(ModelBuilder b)
{
    b.Entity<Order>(e =>
    {
        e.HasKey(o => o.Id);
        e.Property(o => o.Reference).HasMaxLength(40).IsRequired();
        e.Property(o => o.Total).HasPrecision(18, 2);
        e.HasIndex(o => o.Reference).IsUnique();
        e.HasMany(o => o.Lines)
         .WithOne(l => l.Order)
         .OnDelete(DeleteBehavior.Cascade);
    });
}

Data annotations, the shorter alternative

[Table("orders")]
public class Order
{
    [Key] public Guid Id { get; set; }
    [MaxLength(40), Required] public string Reference { get; set; } = "";
    [Precision(18, 2)] public decimal Total { get; set; }
    [NotMapped] public bool IsLarge => Total > 1000m;
}

A single test, arrange act assert

public class BasketTests
{
    [Fact]
    public void Total_sums_every_line()
    {
        var basket = new Basket();               // arrange
        basket.Add(new Line("apple", 2, 1.50m));

        decimal total = basket.Total;            // act

        Assert.Equal(3.00m, total);              // assert
    }
}

One test, many inputs

[Theory]
[InlineData(0, "empty")]
[InlineData(1, "single")]
[InlineData(9, "many")]
public void Describes_the_count(int count, string expected)
    => Assert.Equal(expected, Basket.Describe(count));

Complex cases from a member or class source

public static TheoryData<decimal, decimal> Discounts => new()
{
    { 100m, 0m },
    { 500m, 25m },
    { 2000m, 200m }
};

[Theory]
[MemberData(nameof(Discounts))]
public void Applies_the_right_discount(decimal total, decimal expected)
    => Assert.Equal(expected, Pricing.Discount(total));

Setup and teardown are the constructor and Dispose

public class DbTests : IDisposable
{
    private readonly SqliteConnection _conn;
    public DbTests() => _conn = OpenTestDatabase();   // before each test
    public void Dispose() => _conn.Dispose();         // after each test
}

Moq, the most common mocking library

var repo = new Mock<IOrderRepository>();
repo.Setup(r => r.GetAsync(It.IsAny<Guid>()))
    .ReturnsAsync(new Order { Total = 50m });

var service = new OrderService(repo.Object, NullLogger<OrderService>.Instance);
await service.GetAsync(Guid.NewGuid());

repo.Verify(r => r.GetAsync(It.IsAny<Guid>()), Times.Once);

NSubstitute reads a little lighter

var repo = Substitute.For<IOrderRepository>();
repo.GetAsync(Arg.Any<Guid>()).Returns(new Order());

await repo.Received(1).GetAsync(Arg.Any<Guid>());

A hand written fake, often the better option

public class FakeClock(DateTimeOffset now) : IClock
{
    public DateTimeOffset UtcNow { get; set; } = now;
    public void Advance(TimeSpan by) => UtcNow = UtcNow.Add(by);
}

Fake the clock with TimeProvider, .NET 8

var time = new FakeTimeProvider(DateTimeOffset.Parse("2026-01-01Z"));
var service = new TrialService(time);
time.Advance(TimeSpan.FromDays(31));
Assert.True(service.HasExpired());

Spin up the real app in memory

public class OrdersApiTests(WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    [Fact]
    public async Task Get_unknown_order_returns_404()
    {
        HttpClient client = factory.CreateClient();
        var res = await client.GetAsync($"/orders/{Guid.NewGuid()}");
        Assert.Equal(HttpStatusCode.NotFound, res.StatusCode);
    }
}

Swap a real dependency for a test one

var client = factory.WithWebHostBuilder(b =>
    b.ConfigureServices(s =>
    {
        s.RemoveAll<IEmailSender>();
        s.AddSingleton<IEmailSender, RecordingSender>();
    })).CreateClient();

An in memory database for EF tests

var options = new DbContextOptionsBuilder<ShopContext>()
    .UseSqlite("DataSource=:memory:")
    .Options;

using var db = new ShopContext(options);
await db.Database.OpenConnectionAsync();
await db.Database.EnsureCreatedAsync();

Create the project and reference the code under test

dotnet new xunit -o Shop.Tests
dotnet add Shop.Tests reference Shop/Shop.csproj
dotnet add Shop.Tests package Moq

Run, filter and collect coverage

dotnet test
dotnet test --filter "FullyQualifiedName~BasketTests"
dotnet test --filter "Category=Integration"
dotnet test --logger "console;verbosity=detailed"
dotnet test --collect:"XPlat Code Coverage"

Skip a test, and group them with traits

[Fact(Skip = "flaky until the sandbox is fixed")]
public void Charges_the_card() { }

[Trait("Category", "Integration")]
public class SlowTests { }

Apply metadata to any member

[Obsolete("Use SendAsync instead")]
[Serializable]
public void Send() { }

Define your own

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public sealed class RouteAttribute : Attribute
{
    public string Template { get; }
    public RouteAttribute(string template) => Template = template;
}

Read types and members at runtime

Type t = typeof(Order);
foreach (var p in t.GetProperties())
    Console.WriteLine($"{p.PropertyType.Name} {p.Name}");

var attr = t.GetCustomAttribute<RouteAttribute>();
object? instance = Activator.CreateInstance(t);

Caller info, free diagnostics

void Trace(string msg,
    [CallerMemberName] string caller = "",
    [CallerLineNumber] int line = 0)
    => Console.WriteLine($"{caller}:{line} {msg}");

Conditional compilation

#if DEBUG
    Console.WriteLine("debug build");
#elif RELEASE
    Log.Minimal();
#endif

#warning revisit before release
#pragma warning disable CS8618

Pointers, only inside an unsafe context

unsafe
{
    int value = 42;
    int* p = &value;
    Console.WriteLine(*p);
}
// requires <AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Stack allocation, no garbage collector pressure

Span<byte> buffer = stackalloc byte[256];

Create, build, run

dotnet new console -o MyApp
dotnet new webapi -o MyApi
dotnet new classlib -o MyLib
dotnet build
dotnet run
dotnet watch run

Packages, references, solutions

dotnet add package Serilog
dotnet remove package Serilog
dotnet add reference ../MyLib/MyLib.csproj
dotnet new sln -n MySolution
dotnet sln add MyApp/MyApp.csproj
dotnet restore

Test, format, publish

dotnet test
dotnet test --filter "FullyQualifiedName~Orders"
dotnet format
dotnet publish -c Release -r linux-x64 --self-contained
dotnet --list-sdks

A minimal project file

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>

Things that surprise almost every newcomer

7 / 2            // 3, not 3.5, both operands are int
"a" == "a"       // true, string overloads ==
obj1 == obj2     // reference equality unless overloaded
struct copies    // assignment copies the whole value
foreach var      // the loop variable is per iteration since C# 5
switch fallthrough  // not allowed, every case needs break
array.Length     // arrays use Length, lists use Count

Naming conventions differ from both languages

PascalCase   types, methods, properties, constants, enum members
camelCase    locals and parameters
_camelCase   private fields
IPascalCase  interfaces
TPascalCase  generic type parameters
NameAsync    asynchronous methods