Learn C# / .NET 8 by building one chat backend ⚙️

You compile C# to Intermediate Language, not machine code. At runtime the .NET runtime loads it and the Just-In-Time compiler turns methods into native code on first use. You never call free(). The garbage collector reclaims objects nothing points to anymore.

// C# 12 top-level program — this IS a full app
using System;
Console.WriteLine("MiniChat backend booting…");
// compiles to IL → JIT compiles WriteLine to native on first call

Now the words: the runtime is the CLR (Common Language Runtime). The portable bytecode is IL / MSIL. Code the CLR manages (memory, safety) is managed code. Skipping IL to precompile is AOT (Native AOT in .NET 8).

A struct is a value type: assigning or passing it copies the whole thing. A class is a reference type: you copy only the address, not the object. Click below to feel the difference.

struct Vote { public int Score; }   // value → copied
class  Msg  { public int Score; }   // reference → shared

Now the words: value types usually live on the stack (fast, auto-freed when the method returns) or inline inside their owner; reference-type objects live on the heap (GC-managed). Local reference variables sit on the stack but point to the heap.

Use properties (get/set) instead of raw fields so you control access. Use an interface to say "any class that promises these methods can be plugged in here." Use a record when the object is defined by its data and two with the same data should count as equal.

// record: value equality + immutable by default (C# 12)
public record ChatMessage(string Role, string Text);

// interface: a contract the LLM client must satisfy
public interface IChatClient {
    Task<string> CompleteAsync(string prompt);
}

// property with validation via the receptionist
public class Conversation {
    private string _title = "";
    public string Title {
        get => _title;
        set => _title = value?.Trim() ?? "";
    }
}

Now the words: a class implementing an interface is polymorphism — swap a real Bedrock client for a fake in tests. Records generate value-based Equals/GetHashCode and support non-destructive mutation: msg with { Text = "edited" }.

Turn on nullable reference types and the type string means "never null," while string? means "might be null." Then two operators keep code short: ?. (do this only if not null) and ?? (use this fallback if null).

string? raw = msg.Text;                 // ? = may be null
int len   = raw?.Length ?? 0;         // ?. skips if null, ?? falls back
string safe = raw ?? "(empty message)";   // never null after this

Now the words: ?. is the null-conditional operator, ?? is the null-coalescing operator, ??= assigns only if currently null. Enable it project-wide with <Nullable>enable</Nullable>.

Store messages in a List<ChatMessage> and lookups in a Dictionary. Then LINQ reads like a sentence: filter, transform, group, fold. And it's lazy — the query is a plan; it runs when you iterate it.

var userWords = messages
    .Where(m => m.Role == "user")         // keep user msgs
    .Select(m => m.Text.Length)             // reshape → lengths
    .Where(len => len > 0);              // still just a plan!

int total = userWords.Sum();               // NOW it iterates + runs

var byRole = messages
    .GroupBy(m => m.Role)
    .ToDictionary(g => g.Key, g => g.Count());  // {"user":3,"assistant":2}

Now the words: LINQ methods take lambdas and return IEnumerable<T> that runs lazily (deferred execution). Aggregate is the general fold; Sum/Count/Max are shortcuts. Dictionary<K,V> gives O(1) lookups by key.

A delegate is a variable that holds a method. The built-ins cover almost everything: Action (takes args, returns nothing), Func (returns a value), Predicate (returns bool). A lambda x => x*2 is just an inline method you hand to one of these.

// Func/Action: behavior as a parameter
Func<string,int> length = s => s.Length;   // returns a value
Action<string>     log    = t => Console.WriteLine(t); // returns void

// event: publisher notifies subscribers
public event Action<string>? OnToken;
OnToken?.Invoke(token);   // ?. so it's safe with zero subscribers

Now the words: a delegate is a type-safe method pointer. Events are delegates with restricted access (only the owner can Invoke). Multiple methods on one delegate = a multicast delegate.

A generic leaves a type as a blank T to be filled in at the call site. A constraint says "T must be at least this" so you can actually use it — e.g. where T : class or where T : IChatClient.

public class Cache<TKey, TValue> where TKey : notnull {
    private readonly Dictionary<TKey,TValue> _map = new();
    public void Set(TKey k, TValue v) => _map[k] = v;
    public bool TryGet(TKey k, out TValue? v) => _map.TryGetValue(k, out v);
}

var convos  = new Cache<string, Conversation>();   // type-safe
var tokens  = new Cache<int, string>();            // no boxing of int

// constrained generic: T must implement the contract
public T First<T>(IEnumerable<T> xs) where T : IChatClient => xs.First();

Now the words: T is a type parameter. where T : … is a constraint (class, struct, new(), an interface, or notnull). Generics are reified in .NET — List<int> and List<string> are genuinely different types at runtime.

Mark a method async and it can await a slow operation. At the await, the thread is released back to the pool to do other work. When the work finishes, execution resumes right after the await. A Task is the order ticket; Task<T> is a ticket that comes back with a value.

public async Task<string> CompleteAsync(string prompt, CancellationToken ct) {
    var reply = await _bedrock.ConverseAsync(prompt, ct); // thread freed here
    return reply.Text;                                  // resumes when reply arrives
}

CancellationToken: the user closed the tab mid-stream — stop calling Bedrock and stop billing. You thread a CancellationToken through every async call; when it's cancelled, the operation bails early. ConfigureAwait(false): in library code, "I don't need to resume on the original context," which avoids the deadlock above and is slightly faster.

// yield each token as it arrives — caller awaits the stream
public async IAsyncEnumerable<string> StreamAsync(
        string prompt, [EnumeratorCancellation] CancellationToken ct) {
    await foreach (var chunk in _bedrock.ConverseStreamAsync(prompt, ct))
        yield return chunk.Text;   // pushes one token to the caller
}

Now the words: Task/Task<T> represent a future result. async+await compile to a state machine. The freed thread returns to the thread pool. ValueTask avoids an allocation when the result is often already available. async void is only for event handlers — never elsewhere (see anti-patterns).

Anything holding an OS resource implements IDisposable with a Dispose() method. Wrap it in using and Dispose() is called automatically when the block ends — guaranteed, even if an exception is thrown.

// using declaration (C# 8+): disposed at end of scope
using var stream = await _bedrock.GetStreamAsync(ct);
await Pump(stream, ct);   // even if this throws, stream.Dispose() still runs

// async cleanup for async resources
await using var conn = new SqlConnection(cs);

Now the words: using compiles to try/finally that calls Dispose(). For your own type, implement IDisposable (or IAsyncDisposable for async cleanup). The full dispose pattern (with a Dispose(bool) and finalizer) is only needed when you hold unmanaged handles directly.

Catch the most specific exception you can actually handle. Let the ones you can't handle bubble up. Use finally for cleanup that must always run, and when filters to catch conditionally.

try {
    return await _bedrock.ConverseAsync(prompt, ct);
}
catch (ThrottlingException ex) when (retries < 3) {  // filter
    _log.LogWarning(ex, "Bedrock throttled, retrying");
    return await RetryAsync(prompt, ct);
}
catch (OperationCanceledException) {                    // user left
    throw;   // re-throw — NOT our job to swallow cancellation
}
finally {
    _metrics.Record(sw.Elapsed);   // always runs
}

Now the words: exceptions unwind the stack until a matching catch. Prefer specific types; use exceptions for the exceptional, not for normal control flow (they're expensive). when is an exception filter that catches without unwinding if false.

You declare what you need in the constructor; the DI container supplies it. You register each service once with a lifetime that says how long one instance lives.

// Program.cs — register once
builder.Services.AddSingleton<IChatClient, BedrockChatClient>();  // shared
builder.Services.AddScoped<IMessageStore, EfMessageStore>();       // per request
builder.Services.AddTransient<PromptBuilder>();                    // each time

// consume — just ask for it in the constructor (primary ctor, C# 12)
public class ChatService(IChatClient chat, IMessageStore store) {
    // chat + store are handed to you, already built
}

Now the words: this is Inversion of Control via constructor injection. The container resolves the whole dependency graph. Depend on the interface, not the concrete class, so tests can inject a fake.

The middleware pipeline is an ordered chain every request flows through. Model binding automatically turns the JSON body into your ChatRequest record. DI hands your service to the endpoint.

// Program.cs — minimal API (C# 12, .NET 8)
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<ChatService>();
var app = builder.Build();

app.UseSerilogRequestLogging();   // middleware, in order
app.UseAuthentication();
app.UseAuthorization();

// body auto-binds to the record; service auto-injected
app.MapPost("/chat", async (ChatRequest req, ChatService svc, CancellationToken ct) =>
{
    var reply = await svc.CompleteAsync(req.Message, ct);
    return Results.Ok(new ChatResponse(reply));
});

// streaming variant → yields tokens to the frontend
app.MapGet("/chat/stream", (string q, ChatService svc, CancellationToken ct)
    => svc.StreamAsync(q, ct));   // IAsyncEnumerable → streamed JSON

app.Run();

public record ChatRequest(string Message, string? ConversationId);
public record ChatResponse(string Reply);

Now the words: middleware is registered with Use… and runs in order (order matters — auth before the endpoint). Model binding maps request data to parameters. Parameters are resolved from the body, route, query, or DI automatically.

EF Core maps classes to tables. The DbContext is your session with the database; it tracks loaded entities so edits get saved automatically. Migrations evolve the schema as your classes change.

public class ChatDb(DbContextOptions<ChatDb> o) : DbContext(o) {
    public DbSet<Conversation> Conversations => Set<Conversation>();
    public DbSet<Message> Messages => Set<Message>();
}

// write: DbContext tracks the new entity, saves in one round trip
db.Messages.Add(new Message { Role = "user", Text = req.Message });
await db.SaveChangesAsync(ct);

// read-only? skip change tracking → faster, less memory
var history = await db.Messages
    .AsNoTracking()
    .Where(m => m.ConversationId == id)
    .ToListAsync(ct);

Now the words: EF Core is an ORM. The DbContext's change tracker diffs loaded entities to generate UPDATE/INSERT. AsNoTracking disables that for read paths. Migrations: dotnet ef migrations add Init then dotnet ef database update.

The AWSSDK.BedrockRuntime package gives you a client. Converse is the unified request — same code for Claude, Llama, Titan. For live typing you use ConverseStream and await foreach the chunks, forwarding each token to your endpoint.

public class BedrockChatClient(IAmazonBedrockRuntime bedrock) : IChatClient {

  public async IAsyncEnumerable<string> StreamAsync(
        string prompt, [EnumeratorCancellation] CancellationToken ct) {

    var req = new ConverseStreamRequest {
        ModelId  = "anthropic.claude-3-5-sonnet-20241022-v2:0",
        Messages = [ new Message {
            Role = ConversationRole.User,
            Content = [ new ContentBlock { Text = prompt } ]
        } ]
    };

    var resp = await bedrock.ConverseStreamAsync(req, ct);

    await foreach (var ev in resp.Stream.WithCancellation(ct))
        if (ev is ContentBlockDeltaEvent d)
            yield return d.Delta.Text;   // one token → to the frontend
  }
}

Now the words: IAmazonBedrockRuntime is registered in DI (AddAWSService). Converse/ConverseStream are the model-agnostic APIs; the streaming response is an event stream of ContentBlockDeltaEvents you filter and yield. Auth is via the standard AWS credential chain (IAM role, env, profile).