C# · Lesson 8

.NET backend building blocks

What day-to-day work on an ASP.NET Core service in the cloud looks like: dependency injection and lifetimes, options and configuration, minimal APIs and controllers, middleware, HttpClient, cloud SDK clients with workload identity, and background services.

14 min read

In short

  • Before Build() registers, after it uses
  • Never depend on a shorter lifetime
  • Config layers: later wins, and __ means :
  • Options: bind, validate, ValidateOnStart()
  • Middleware order: authentication before authorization
  • IHttpClientFactory and singleton cloud SDK clients

On a .NET team you'll mostly add features to services that already exist, so you need to recognise the pieces quickly: where a dependency comes from, why a setting has the value it has, why a request returns 401 before it ever reaches your endpoint. This topic is a map of a typical ASP.NET Core service running in the cloud, plus the mistakes that come up in code review.

ASP.NET Core and the cloud SDKs are NuGet packages, which the lab can't load, so their snippets are marked (not runnable here). The exercises rebuild the mechanisms in plain C# instead: a configuration merger, an options validator, a middleware pipeline, a retrying HttpClient handler, a DI container and a queue worker. Building them is the fastest way to understand what the framework does for you.

A tour of Program.cs

// Program.cs of an ASP.NET Core service (not runnable here)
var builder = WebApplication.CreateBuilder(args);

// 1. Configuration and options: appsettings.json, appsettings.{Environment}.json, user secrets, environment variables
builder.Services.AddOptions<MessagingOptions>()
    .Bind(builder.Configuration.GetSection(MessagingOptions.Section))
    .ValidateDataAnnotations()
    .ValidateOnStart();

// 2. Services for dependency injection
builder.Services.AddDbContext<OrdersDbContext>(o => o.UseSqlServer(builder.Configuration.GetConnectionString("Orders")));
builder.Services.AddScoped<IOrderService, OrderService>();
builder.Services.AddSingleton(TimeProvider.System);
builder.Services.AddHttpClient<IShippingClient, ShippingClient>(c => c.BaseAddress = new Uri("https://shipping.internal/"))
    .AddStandardResilienceHandler();
builder.Services.AddSingleton<IMessagePublisher, QueueMessagePublisher>(); // wraps your cloud's queue SDK client
builder.Services.AddSingleton<IObjectStore, CloudObjectStore>();           // wraps its object storage client
builder.Services.AddHostedService<OrderEventsWorker>();
builder.Services.AddProblemDetails();

var app = builder.Build();

// 3. The middleware pipeline (order matters)
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

// 4. Endpoints
app.MapGet("/orders/{id:int}", async (int id, IOrderService orders, CancellationToken ct) =>
    await orders.FindAsync(id, ct) is { } order ? Results.Ok(order) : Results.NotFound());

app.Run();

Everything before builder.Build() registers things. Everything after it uses them. The rest of this lesson walks through each part.

Dependency injection

Services ask for what they need in their constructor, and the container builds the whole object graph. C# 12 primary constructors make this short:

// (not runnable here)
public sealed class OrderService(OrdersDbContext db, IShippingClient shipping, ILogger<OrderService> logger) : IOrderService
{
    public async Task<Order?> FindAsync(int id, CancellationToken ct) => await db.Orders.FindAsync([id], ct);
}

You register each service with a lifetime:

LifetimeOne instance per...Typical services
AddSingletonapplicationcloud SDK clients (AmazonS3Client, BlobServiceClient, StorageClient), TimeProvider, in-memory caches, IOptions<T>
AddScopedrequest (or scope you create)EF Core DbContext, unit of work, "current user"
AddTransientevery time it's requestedsmall stateless helpers, typed HttpClients

The container also disposes what it created: scoped and transient services when the scope (the request) ends, singletons when the app shuts down. Never dispose an injected service yourself.

Captive dependencies

A service must not depend on something with a shorter lifetime. If a singleton takes a DbContext in its constructor, it gets one from the root scope and keeps it forever: every request shares it. A DbContext isn't thread-safe, its change tracker grows without end, and it holds on to a connection. That's a captive dependency.

// (not runnable here)
builder.Services.AddScoped<OrdersDbContext>();
builder.Services.AddSingleton<PriceCache>();          // PriceCache(OrdersDbContext db): captive!

// In Development, ASP.NET Core validates scopes and fails with:
// InvalidOperationException: Cannot consume scoped service 'OrdersDbContext' from singleton 'PriceCache'.

Scope validation is on by default in the Development environment only. In Production the bug ships silently, which is why it's worth knowing the rule. The fixes:

  • Make the consumer scoped as well, if it doesn't really need to be a singleton.
  • Inject IServiceScopeFactory and create a scope for each unit of work. Background services must do this.
  • For EF Core, inject IDbContextFactory<T> and create a short-lived context when you need one.

Two more registrations you'll see: keyed services (.NET 8), AddKeyedSingleton<IFileStore, LocalFileStore>("local") resolved with [FromKeyedServices("local")], and factories, AddScoped(sp => new X(sp.GetRequiredService<Y>(), "...")).

Angular developers know the idea: providedIn: 'root' is a singleton, and a provider on a component creates a new instance for that part of the tree, much like a scope.

Configuration and the options pattern

Configuration is a stack of key/value providers. Later providers override earlier ones:

  1. appsettings.json
  2. appsettings.{Environment}.json, for example appsettings.Production.json
  3. User secrets, in Development only (dotnet user-secrets set ...)
  4. Environment variables
  5. Command-line arguments

Keys are case-insensitive and sections are separated by :, so Messaging:QueueName is the QueueName inside the Messaging section. Environment variable names can't contain : on every platform, so Messaging__QueueName (double underscore) means the same key. Hosting platforms pass settings as environment variables (an ECS task definition or Lambda configuration on AWS, App Service app settings on Azure, a Cloud Run service on Google Cloud, a pod spec on Kubernetes), which is how a deployment overrides appsettings.json. Secrets come from a secrets store (AWS Secrets Manager, Azure Key Vault, Google Secret Manager, HashiCorp Vault), either through a configuration provider or injected by the platform as environment variables or files. Shared settings and feature flags often come from a configuration service (AWS AppConfig, Azure App Configuration, Google Cloud Parameter Manager, a Kubernetes ConfigMap).

{
  "Messaging": {
    "Host": "orders-dev.mq.internal",
    "QueueName": "orders",
    "MaxConcurrentCalls": 8
  }
}

The options pattern binds a section to a class and validates it at startup:

// (not runnable here)
public sealed class MessagingOptions
{
    public const string Section = "Messaging";

    [Required] public string Host { get; set; } = "";
    [Required] public string QueueName { get; set; } = "";
    [Range(1, 100)] public int MaxConcurrentCalls { get; set; } = 4;
}

builder.Services.AddOptions<MessagingOptions>()
    .Bind(builder.Configuration.GetSection(MessagingOptions.Section))
    .ValidateDataAnnotations()                       // the attributes above
    .Validate(o => !o.QueueName.Contains(' '), "QueueName can't contain spaces")
    .ValidateOnStart();                              // fail at startup, not on the first message at 3 a.m.

Consume it through one of three interfaces:

InterfaceLifetimeSees changes to config?
IOptions<T>singletonno, it's read once
IOptionsSnapshot<T>scopedyes, recomputed for each request
IOptionsMonitor<T>singletonyes, CurrentValue plus an OnChange callback

IOptionsSnapshot<T> is scoped, so a singleton can't take it (captive dependency again). Singletons that need live values use IOptionsMonitor<T>. For rules that don't fit attributes, implement IValidateOptions<T>, which exercise 2 does.

Minimal APIs and controllers

Both run on the same pipeline, DI container and model binding. New services often use minimal APIs; many existing services use controllers. Follow whatever your codebase already does.

// Minimal API (not runnable here)
var orders = app.MapGroup("/orders").RequireAuthorization();

orders.MapGet("/{id:int}", async Task<Results<Ok<OrderDto>, NotFound>> (int id, IOrderService service, CancellationToken ct) =>
    await service.FindAsync(id, ct) is { } order ? TypedResults.Ok(order) : TypedResults.NotFound());

orders.MapPost("/", async (CreateOrder command, IOrderService service, CancellationToken ct) =>
{
    var created = await service.CreateAsync(command, ct);
    return TypedResults.Created($"/orders/{created.Id}", created);
});
// Controller (not runnable here)
[ApiController]
[Route("orders")]
public sealed class OrdersController(IOrderService service) : ControllerBase
{
    [HttpGet("{id:int}")]
    public async Task<ActionResult<OrderDto>> Get(int id, CancellationToken ct) =>
        await service.FindAsync(id, ct) is { } order ? Ok(order) : NotFound();
}

Parameters bind from the route (id), the query string, the JSON body (CreateOrder), DI (IOrderService) and the request itself (CancellationToken, HttpContext). [ApiController] adds automatic 400 responses for invalid models. TypedResults gives minimal APIs typed responses that show up in the OpenAPI document.

The middleware pipeline

Every request passes through a chain of middleware. Each one receives the HttpContext and a next delegate. It can do work before calling next, after it returns, or not call it at all (short-circuit, for example to return a 401). The result is an onion: the first middleware registered is the outermost layer.

Here's the same mechanism in plain C#, with delegates:

▶ Try
var log = new List<string>();

Func<Func<Task>, Func<Task>> Middleware(string name) => next => async () =>
{
    log.Add($"{name}: before");
    await next();
    log.Add($"{name}: after");
};

Func<Task> endpoint = () => { log.Add("endpoint"); return Task.CompletedTask; };

// Wrap from the inside out: the first middleware in the list ends up outermost.
var pipeline = new[] { Middleware("exception handler"), Middleware("authentication"), Middleware("logging") }
    .Reverse()
    .Aggregate(endpoint, (next, middleware) => middleware(next));

await pipeline();
Console.WriteLine(string.Join(Environment.NewLine, log));

And the real thing:

// ASP.NET Core (not runnable here)
app.Use(async (context, next) =>
{
    var started = Stopwatch.GetTimestamp();
    await next(context);
    logger.LogInformation("{Method} {Path} returned {Status} in {Elapsed} ms",
        context.Request.Method, context.Request.Path, context.Response.StatusCode,
        Stopwatch.GetElapsedTime(started).TotalMilliseconds);
});

Order matters. The exception handler goes first so it wraps everything. UseAuthentication (who are you?) must come before UseAuthorization (are you allowed?), or every user looks anonymous. CORS goes before authentication so that preflight requests aren't rejected. Endpoints are the exception to "order of the calls": WebApplication runs every app.Map... endpoint at the end of the pipeline, so a middleware added with app.Use after app.MapGet still runs before the endpoint.

HttpClient and IHttpClientFactory

Two classic mistakes:

  • new HttpClient() for every call. Each instance has its own connection pool, and closed sockets linger in TIME_WAIT. Under load you run out of sockets ("socket exhaustion").
  • One static HttpClient forever. Its connections never close, so it never sees DNS changes, for example during a failover. (Setting SocketsHttpHandler.PooledConnectionLifetime fixes that.)

IHttpClientFactory solves both: it pools and recycles the underlying handlers and plugs into DI, logging and resilience. A typed client is the usual shape:

// (not runnable here)
builder.Services.AddHttpClient<IShippingClient, ShippingClient>(client =>
{
    client.BaseAddress = new Uri("https://shipping.internal/");
    client.Timeout = TimeSpan.FromSeconds(10);
})
.AddHttpMessageHandler<CorrelationIdHandler>()
.AddStandardResilienceHandler(); // retries, circuit breaker and timeouts (Microsoft.Extensions.Http.Resilience)

public sealed class ShippingClient(HttpClient http) : IShippingClient
{
    public async Task<Tracking?> GetTrackingAsync(string code, CancellationToken ct)
    {
        using var response = await http.GetAsync($"tracking/{Uri.EscapeDataString(code)}", ct);
        if (response.StatusCode == HttpStatusCode.NotFound) return null;
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<Tracking>(ct);
    }
}

Typed clients are transient, so don't store one in a singleton: that's a captive dependency that defeats the handler recycling. Between HttpClient and the network sits a pipeline of DelegatingHandlers, the client-side version of middleware. Those classes are part of the base library, so this runs here:

▶ Try
using System.Net;

var handler = new LoggingHandler { InnerHandler = new FakeApi() };
using var http = new HttpClient(handler) { BaseAddress = new Uri("https://api.example.com/") };
var response = await http.GetAsync("orders/42");
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

sealed class LoggingHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
    {
        Console.WriteLine($"-> {request.Method} {request.RequestUri}");
        var response = await base.SendAsync(request, ct); // the next handler in the chain
        Console.WriteLine($"<- {(int)response.StatusCode}");
        return response;
    }
}

// Stands in for the network, so the example runs without one.
sealed class FakeApi : HttpMessageHandler
{
    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct) =>
        Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{\"id\":42}") });
}

Exercise 4 writes a retrying handler with the same base class.

Cloud SDK clients and workload identity

Every cloud ships .NET clients for its services. They're thread-safe and expensive to create (they hold connection pools, and some keep AMQP or gRPC channels open), so register them as singletons and reuse them. A new database client per request is a well-known way to exhaust connections.

KindAWSAzureGoogle CloudOther
Message queueAmazonSQSClient (SQS)ServiceBusClient (Service Bus)PublisherClient, SubscriberClient (Pub/Sub)RabbitMQ.Client, Confluent.Kafka
Object storageAmazonS3Client (S3)BlobServiceClient (Blob Storage)StorageClient (Cloud Storage)MinIO (speaks the S3 API)
Document databaseAmazonDynamoDBClient (DynamoDB)CosmosClient (Cosmos DB)FirestoreDb (Firestore)MongoDB.Driver
Secrets storeAmazonSecretsManagerClientSecretClient (Key Vault)SecretManagerServiceClientVaultSharp (HashiCorp Vault)

Each SDK has a DI helper: AddAWSService<IAmazonS3>() (AWSSDK.Extensions.NETCore.Setup), AddAzureClients(...) (Microsoft.Extensions.Azure), and the Add...Client() extensions in Google's libraries. Business code usually doesn't take the SDK client directly. It depends on a small interface of your own, so handlers read like the domain, tests can use an in-memory fake, and the SDK details live in one class:

// Your own abstractions (not runnable here). One implementation per provider wraps that provider's SDK client.
public sealed record OutgoingMessage(string Id, string Type, string Json);

public interface IMessagePublisher
{
    Task PublishAsync(string queue, OutgoingMessage message, CancellationToken ct);
}

public interface IObjectStore
{
    Task UploadAsync(string container, string name, Stream content, CancellationToken ct);
}

// In a handler
await publisher.PublishAsync("orders", new OutgoingMessage(
    Id: order.Id.ToString(),   // lets the broker or the consumer drop resends
    Type: "OrderPlaced",
    Json: JsonSerializer.Serialize(order)), ct);
await objects.UploadAsync("invoices", $"{order.Id}.pdf", pdfStream, ct);

No connection strings, no keys. In the cloud the app runs with a workload identity that the platform gives it: an IAM role for the ECS task, Lambda function or EKS pod on AWS; a managed identity on App Service, Functions, Container Apps or AKS on Azure; an attached service account on Cloud Run, GKE or Compute Engine on Google Cloud. Each SDK finds credentials through a default chain that checks environment variables, your developer sign-in (aws sso login, az login, gcloud auth application-default login) and the platform's identity. In .NET that's the AWS SDK's default credentials, DefaultAzureCredential and Google's Application Default Credentials. The order differs: the AWS SDK and Google's chain try your local sign-in before the platform's identity, while DefaultAzureCredential tries the managed identity first. A production machine has no developer sign-in, so the same code uses your own account on your laptop and the app's identity in production. Some teams pin the production credential explicitly, so a misconfigured app fails clearly instead of probing the whole chain.

Access is granted by giving that identity a permission on the resource: an IAM policy that allows sqs:SendMessage or s3:PutObject on AWS, a data role such as "Storage Blob Data Contributor" on Azure, a role such as roles/pubsub.publisher on Google Cloud. The classic first-week puzzle "it works on my machine but returns 403 in production" almost always means the workload identity has no permission on that resource (or it was just granted and hasn't propagated yet).

Queue semantics you'll rely on: a receiver gets a message under a lock (SQS calls it a visibility timeout, Service Bus peek-lock, Pub/Sub an ack deadline). Completing (acknowledging) it removes it; abandoning it, or letting the lock run out, releases it for another try, which increases its delivery count. After a configured number of attempts (SQS maxReceiveCount, Service Bus MaxDeliveryCount, Pub/Sub maxDeliveryAttempts, a RabbitMQ quorum queue's delivery limit), the broker moves it to a dead-letter queue. You can also dead-letter a message yourself when retrying can't help (bad JSON). Delivery is at least once, so handlers must be idempotent: processing the same message twice must not charge a customer twice.

Background services

Long-running work, such as consuming a queue or a periodic cleanup, runs in a BackgroundService. Hosted services are singletons, so anything scoped must come from a scope you create per unit of work:

// .NET worker (not runnable here). IMessageConsumer is your wrapper over SQS, Service Bus, Pub/Sub or RabbitMQ.
public sealed class OrderEventsWorker(
    IMessageConsumer consumer, IServiceScopeFactory scopes, ILogger<OrderEventsWorker> logger) : BackgroundService
{
    protected override Task ExecuteAsync(CancellationToken stoppingToken) =>
        Parallel.ForEachAsync(
            consumer.ReceiveAllAsync("orders", stoppingToken),  // IAsyncEnumerable<ReceivedMessage>
            new ParallelOptions { MaxDegreeOfParallelism = 8, CancellationToken = stoppingToken },
            async (message, ct) =>
            {
                await using var scope = scopes.CreateAsyncScope(); // a fresh DbContext for every message
                var handler = scope.ServiceProvider.GetRequiredService<IOrderEventHandler>();
                try
                {
                    await handler.HandleAsync(message, ct);
                    await consumer.CompleteAsync(message, ct);
                }
                catch (Exception e)
                {
                    if (!ct.IsCancellationRequested)
                        logger.LogError(e, "Message {MessageId} failed", message.Id);
                    await consumer.AbandonAsync(message, CancellationToken.None); // back on the queue for another try
                }
            });
}

On shutdown, stoppingToken fires and the host waits a limited time (HostOptions.ShutdownTimeout) for ExecuteAsync to finish. Broker SDKs and frameworks also ship ready-made processors that run this loop (Azure's ServiceBusProcessor, Pub/Sub's SubscriberClient, the AWS Message Processing Framework for .NET, MassTransit), and exercise 6 builds one so you know what they do. Serverless functions triggered by the queue (AWS Lambda with an SQS event source, Azure Functions with a Service Bus trigger, Cloud Run functions with a Pub/Sub trigger) are the other common home for queue handlers: the platform runs the loop and you write only the handler.

Common mistakes in code review

  • A captive dependency: a scoped service, IOptionsSnapshot<T> or a typed HttpClient inside a singleton.
  • new HttpClient() per call, or a new cloud SDK client (queue, storage, database) per request.
  • IOptions<T> where the value must follow config changes (use IOptionsMonitor<T>).
  • Secrets in appsettings.json committed to git. Use user secrets locally, and a secrets store or workload identity in production.
  • .Result or .Wait() in startup code or in a hosted service's StartAsync, which blocks the whole app from starting.
  • An endpoint that doesn't pass its CancellationToken on.
  • Middleware in the wrong order: authorization before authentication, or the exception handler registered last.
  • Message handlers that aren't idempotent, although queues deliver at least once.

The exercises

  1. Configuration layers: merge settings layers the way IConfiguration does, with __ keys and sections.
  2. Options validation: an IValidateOptions<T> validator that reports every problem at startup.
  3. Middleware pipeline: ASP.NET Core's Use, Run and Map built from delegates.
  4. Retrying message handler: a real DelegatingHandler that retries transient failures and honours Retry-After.
  5. DI container: singleton, scoped and transient lifetimes, disposal, and captive-dependency detection.
  6. Queue worker: a queue processor like the ones the cloud SDKs ship, with concurrency, retries, dead-lettering and graceful shutdown.

Practise this lesson

In the app: a short video, 6 exercises checked by real tests and a 10-question concept check. Free with a GitHub account. Running the exercises against their tests needs Pro.

Open in the app