Foundations: computer science & system design basics

public sealed class Account
{
    private readonly Lock _gate = new();   // .NET 9+ dedicated lock type
    private decimal _balance;
    private long _requests;

    public void Deposit(decimal amount)
    {
        Interlocked.Increment(ref _requests);   // lock-free counter
        lock (_gate) { _balance += amount; }    // one thread at a time
    }
}

Never hold a lock across an await (the compiler blocks it). Use SemaphoreSlim.WaitAsync when async code needs mutual exclusion.

// Concurrency (I/O-bound): up to 8 calls in flight at once
await Parallel.ForEachAsync(accountIds,
    new ParallelOptions { MaxDegreeOfParallelism = 8, CancellationToken = ct },
    async (id, token) => await client.RefreshBalanceAsync(id, token));

// Parallelism (CPU-bound): spread the work across cores
var totals = transactions.AsParallel()
    .GroupBy(t => t.AccountId)
    .Select(g => (Account: g.Key, Total: g.Sum(t => t.Amount)))
    .ToList();

Don't wrap I/O calls in Task.Run or PLINQ to "make them parallel". Async I/O is already concurrent; extra threads only add overhead.

builder.Services.AddSingleton(Channel.CreateBounded<ReportJob>(100));
builder.Services.AddHostedService<ReportWorker>();

app.MapPost("/reports", async (ReportRequest req, Channel<ReportJob> queue) =>
{
    var job = new ReportJob(Guid.NewGuid(), req);
    await queue.Writer.WriteAsync(job);
    return TypedResults.Accepted($"/reports/{job.Id}", new { job.Id });   // 202 + where to poll
});

public sealed class ReportWorker(Channel<ReportJob> queue) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        await foreach (var job in queue.Reader.ReadAllAsync(ct))
            await BuildReportAsync(job, ct);
    }
}

Never block on async code with .Result or .Wait(). It ties up thread-pool threads and can starve the whole server under load.

public sealed class PaymentMetrics(IMeterFactory meterFactory)
{
    private readonly Histogram<double> _duration = meterFactory.Create("Bank.Payments")
        .CreateHistogram<double>("payments.duration", unit: "s");

    public async Task<T> TimeAsync<T>(Func<Task<T>> work)
    {
        var start = Stopwatch.GetTimestamp();
        try { return await work(); }
        finally { _duration.Record(Stopwatch.GetElapsedTime(start).TotalSeconds); }
    }
}

public sealed class Account
{
    public Guid Id { get; set; }
    public decimal Balance { get; set; }
    [Timestamp] public byte[] RowVersion { get; set; } = [];   // concurrency token
}

// Optimistic: EF sends UPDATE ... WHERE Id = @id AND RowVersion = @original
try
{
    account.Balance -= amount;
    await db.SaveChangesAsync(ct);
}
catch (DbUpdateConcurrencyException)
{
    // Someone wrote first: reload, re-check the rule, then retry or return 409
}

// Lock-free counter and CAS
Interlocked.Increment(ref _requests);
Interlocked.CompareExchange(ref _config, newConfig, oldConfig);  // swap only if unchanged

ConcurrentDictionary.GetOrAdd can run the value factory more than once under a race. Keep the factory cheap and side-effect free, or store a Lazy<T>.

// An actor in miniature: one mailbox, one reader, private state, no locks
public sealed class AccountActor
{
    private readonly Channel<decimal> _mailbox = Channel.CreateBounded<decimal>(
        new BoundedChannelOptions(1_000) { SingleReader = true, FullMode = BoundedChannelFullMode.Wait });
    private decimal _balance;   // only RunAsync touches it

    public ValueTask PostAsync(decimal amount, CancellationToken ct) =>
        _mailbox.Writer.WriteAsync(amount, ct);   // waits when full: back-pressure

    public async Task RunAsync(CancellationToken ct)   // start once, e.g. from a BackgroundService
    {
        await foreach (var amount in _mailbox.Reader.ReadAllAsync(ct))
            _balance += amount;   // one message at a time
    }
}

Orleans grains are non-reentrant by default: if grain A awaits B and B calls back into A, they deadlock until the request times out. Avoid call cycles, or allow reentrancy on purpose (RequestContext.AllowCallChainReentrancy(), [AlwaysInterleave] or [Reentrant]).

# install once (or copy the single-file builds into the container)
dotnet tool install --global dotnet-counters
dotnet tool install --global dotnet-trace
dotnet tool install --global dotnet-dump

# memory climbing toward the limit? watch it live
dotnet-counters monitor -n PaymentsApi --counters System.Runtime,System.Net.Http

# where is the CPU going? (Ctrl+C to stop)
dotnet-trace collect -p 4242

# what is holding the memory? dump before the OOM kill, then inspect
dotnet-dump collect -p 4242
dotnet-dump analyze <dump-file>   # then: dumpheap -stat, gcroot <address>

An OOM kill is SIGKILL: no exception, no crash dump. Alert on working set near the limit and capture a dump while it climbs.

// Append-only journal: sequential writes, durable on return
var opts = new FileStreamOptions
{
    Mode = FileMode.Append, Access = FileAccess.Write, Share = FileShare.Read,
    BufferSize = 64 * 1024, Options = FileOptions.Asynchronous
};
await using var journal = new FileStream("payments.journal", opts);
await journal.WriteAsync(record, ct);   // in .NET's buffer / OS page cache
journal.Flush(flushToDisk: true);       // fsync: now it survives a power cut

// Cache-friendly: contiguous structs and a pooled buffer
public readonly record struct Tick(long Time, decimal Price);
byte[] buffer = ArrayPool<byte>.Shared.Rent(81_920);
try { /* read into buffer.AsSpan() */ }
finally { ArrayPool<byte>.Shared.Return(buffer); }

// Columnar export for analytics
await ParquetSerializer.SerializeAsync(transactions, "tx-2026-10.parquet");

Flush() and FlushAsync() only move .NET's buffer into the OS page cache. For durability use Flush(true) or FileOptions.WriteThrough, and batch writes so you don't fsync per record.

// Top-K largest payments: keep a min-heap of size K, O(n log K)
static List<Payment> TopK(IEnumerable<Payment> all, int k)
{
    var heap = new PriorityQueue<Payment, decimal>(k);
    foreach (var p in all)
    {
        if (heap.Count < k) heap.Enqueue(p, p.Amount);
        else if (p.Amount > heap.Peek().Amount) heap.EnqueueDequeue(p, p.Amount);
    }
    return heap.UnorderedItems.Select(x => x.Element)
               .OrderByDescending(p => p.Amount).ToList();
}

// Ring-buffer style log queue: never grows, drops the oldest when full
var logs = Channel.CreateBounded<string>(new BoundedChannelOptions(10_000)
    { FullMode = BoundedChannelFullMode.DropOldest, SingleReader = true });

var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(k => k.ListenAnyIP(5001, o =>
{
    o.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;   // needs MsQuic
    o.UseHttps();
}));
builder.Services.AddResponseCompression();
builder.Services.AddOutputCache();

var app = builder.Build();
app.UseHsts();
app.UseHttpsRedirection();
app.UseResponseCompression();
app.UseOutputCache();

app.MapGet("/rates", () => Rates.Today())
   .CacheOutput(p => p.Expire(TimeSpan.FromSeconds(30)));
app.Run();

HTTP/3 in .NET needs MsQuic: built in on Windows 11 / Server 2022+, install libmsquic on Linux. Always keep HTTP/1.1 and HTTP/2 enabled as a fallback.

// Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddReverseProxy()
       .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));
var app = builder.Build();
app.MapReverseProxy();
app.Run();

// appsettings.json
"ReverseProxy": {
  "Routes": {
    "accounts": {
      "ClusterId": "accounts",
      "Match": { "Path": "/accounts/{**catch-all}" }
    }
  },
  "Clusters": {
    "accounts": {
      "LoadBalancingPolicy": "RoundRobin",
      "HealthCheck": { "Active": { "Enabled": true, "Path": "/health" } },
      "Destinations": {
        "a1": { "Address": "https://accounts-1:8443/" },
        "a2": { "Address": "https://accounts-2:8443/" }
      }
    }
  }
}

YARP is a library, not a product: you host it in ASP.NET Core and add auth, rate limiting and telemetry with normal middleware. For a managed gateway with developer portal and subscriptions, use an APIM product (9.1).

// Custom histogram for one business operation
public sealed class PaymentMetrics
{
    public static readonly Meter Meter = new("Bank.Payments");
    public static readonly Histogram<double> Duration =
        Meter.CreateHistogram<double>("payments.submit.duration", unit: "s");
}

builder.Services.AddOpenTelemetry()
    .WithMetrics(m => m
        .AddMeter("Microsoft.AspNetCore.Hosting")   // http.server.request.duration
        .AddMeter("Bank.Payments")
        .AddOtlpExporter());

var sw = Stopwatch.StartNew();
await payments.SubmitAsync(cmd);
PaymentMetrics.Duration.Record(sw.Elapsed.TotalSeconds,
    new KeyValuePair<string, object?>("channel", "mobile"));

Prove an NFR twice: a load test before release (k6 threshold fails the build) and a p99 SLO alert in production from the same histogram.

// Directory sharding: look up the tenant's shard, then open a context on it
public sealed class ShardedContextFactory(ITenantDirectory directory)
{
    public async Task<PaymentsContext> CreateAsync(string tenantId, CancellationToken ct)
    {
        string conn = await directory.GetConnectionStringAsync(tenantId, ct); // cache this
        var options = new DbContextOptionsBuilder<PaymentsContext>()
            .UseSqlServer(conn).Options;
        return new PaymentsContext(options);
    }
}

// Cosmos DB: hierarchical partition key, tenant then account
Container payments = await database.CreateContainerIfNotExistsAsync(
    new ContainerProperties("payments", ["/tenantId", "/accountId"]));

PartitionKey pk = new PartitionKeyBuilder().Add(p.TenantId).Add(p.AccountId).Build();
await payments.CreateItemAsync(p, pk);   // single-partition write
var read = await payments.ReadItemAsync<Payment>(p.Id, pk); // cheapest read: id + key

// Hot counter: write-shard into 8 sub-keys, sum them on read
string subKey = $"{merchantId}#{Random.Shared.Next(8)}";

A Cosmos DB transaction (TransactionalBatch) only spans one logical partition. Queries without the partition key fan out across partitions and cost more RUs.

// Batch: bounded data, exact answer (EF Core, runs nightly)
var daily = await db.Payments
    .Where(p => p.At >= day && p.At < day.AddDays(1))
    .GroupBy(p => p.AccountId)
    .Select(g => new { AccountId = g.Key, Total = g.Sum(p => p.Amount) })
    .ToListAsync(ct);

// Stream: unbounded data, 1-minute tumbling windows by event time
var channel = Channel.CreateBounded<Payment>(new BoundedChannelOptions(10_000)
    { FullMode = BoundedChannelFullMode.Wait });          // back-pressure

var windows = new Dictionary<DateTime, decimal>();
await foreach (var p in channel.Reader.ReadAllAsync(ct))
{
    var start = new DateTime(p.At.Ticks - p.At.Ticks % TimeSpan.TicksPerMinute, DateTimeKind.Utc);
    windows[start] = windows.GetValueOrDefault(start) + p.Amount;
    // watermark: emit and remove windows older than (latest event time - 2 min)
}

Stick to the in-process Channel for a single service. For durable, replayable, multi-consumer streams use Kafka or Azure Event Hubs.

// Push: a worker drains a bounded channel and broadcasts via SignalR
builder.Services.AddSignalR();
builder.Services.AddSingleton(Channel.CreateBounded<PriceTick>(
    new BoundedChannelOptions(1_000) { FullMode = BoundedChannelFullMode.Wait }));
builder.Services.AddHostedService<PricePusher>();
app.MapHub<PricesHub>("/hubs/prices");

public sealed class PricePusher(Channel<PriceTick> ch, IHubContext<PricesHub> hub) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        await foreach (var t in ch.Reader.ReadAllAsync(ct))
            await hub.Clients.Group(t.Pair).SendAsync("tick", t, ct);
    }
}

// Keyset pagination: index (AccountId, BookedAt, Id)
var page = await db.Transactions
    .Where(t => t.AccountId == accountId &&
                (t.BookedAt < after.BookedAt ||
                 (t.BookedAt == after.BookedAt && t.Id < after.Id)))
    .OrderByDescending(t => t.BookedAt).ThenByDescending(t => t.Id)
    .Take(50)
    .ToListAsync(ct);

Self-hosted SignalR on more than one instance needs a Redis backplane and sticky sessions (unless every client is WebSocket-only). Azure SignalR Service removes both.

builder.Services.AddHttpClient<LedgerClient>(c => c.BaseAddress = new("https://ledger.internal"))
    .AddStandardResilienceHandler(o =>
    {
        o.AttemptTimeout.Timeout = TimeSpan.FromSeconds(2);
        o.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(6);
        o.Retry.MaxRetryAttempts = 2;            // exponential backoff + jitter by default
    });

builder.Services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status503ServiceUnavailable;
    o.AddConcurrencyLimiter("shed", c => { c.PermitLimit = 200; c.QueueLimit = 50; });
});

builder.Services.AddHealthChecks()
    .AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])
    .AddCheck<LedgerReadyCheck>("ledger", tags: ["ready"]);

var app = builder.Build();
app.UseRateLimiter();
app.MapHealthChecks("/health/live",  new() { Predicate = r => r.Tags.Contains("live") });
app.MapHealthChecks("/health/ready", new() { Predicate = r => r.Tags.Contains("ready") });
app.MapPost("/payments", PayAsync).RequireRateLimiting("shed");

Polly has no built-in retry budget. Keep MaxRetryAttempts low, let the circuit breaker stop retry storms, and retry at one layer only.

// Leader-only job with DistributedLock (SQL Server provider)
var leaderLock = new SqlDistributedLock("nightly-settlement", connectionString);
await using var handle = await leaderLock.TryAcquireAsync(TimeSpan.FromSeconds(5), ct);
if (handle is null) return;                        // another node is leader
using var lost = CancellationTokenSource.CreateLinkedTokenSource(ct, handle.HandleLostToken);
await RunSettlementAsync(lost.Token);              // stop if the lock is lost

// Merkle root over key ranges: compare roots first, then children
static byte[] MerkleRoot(IReadOnlyList<byte[]> ranges)
{
    var level = ranges.Select(r => SHA256.HashData(r)).ToList();
    while (level.Count > 1)
    {
        var next = new List<byte[]>();
        for (int i = 0; i < level.Count; i += 2)
        {
            var right = i + 1 < level.Count ? level[i + 1] : level[i]; // odd count: repeat last
            byte[] pair = [.. level[i], .. right];
            next.Add(SHA256.HashData(pair));
        }
        level = next;
    }
    return level[0];
}
bool inSync = MerkleRoot(replicaA).AsSpan().SequenceEqual(MerkleRoot(replicaB));

A lock or lease is not a guarantee of exclusivity after a long GC pause. Pass a fencing token (or row version) to the resource you write.

var builder = WebApplication.CreateBuilder(args);

// Secrets from Key Vault via managed identity (no secrets in appsettings)
builder.Configuration.AddAzureKeyVault(
    new Uri("https://payments-kv.vault.azure.net/"), new DefaultAzureCredential());

// AuthN + AuthZ
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o => { o.Authority = builder.Configuration["Auth:Authority"]; o.Audience = "api://payments"; });
builder.Services.AddAuthorizationBuilder()
    .AddPolicy("payments.write", p => p.RequireRole("Payments.Writer"));

// Traces, metrics and logs; W3C traceparent is propagated automatically
builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r.AddService("payments-api"))
    .WithTracing(t => t.AddAspNetCoreInstrumentation().AddHttpClientInstrumentation().AddOtlpExporter())
    .WithMetrics(m => m.AddAspNetCoreInstrumentation().AddHttpClientInstrumentation().AddOtlpExporter());
builder.Logging.AddOpenTelemetry(o => o.AddOtlpExporter());

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapPost("/payments", CreatePayment).RequireAuthorization("payments.write");
app.Run();

In production, prefer a specific credential such as ManagedIdentityCredential over DefaultAzureCredential, and never log tokens, secrets or full card numbers.