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.
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
IHttpClientFactoryand 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:
| Lifetime | One instance per... | Typical services |
|---|---|---|
AddSingleton | application | cloud SDK clients (AmazonS3Client, BlobServiceClient, StorageClient), TimeProvider, in-memory caches, IOptions<T> |
AddScoped | request (or scope you create) | EF Core DbContext, unit of work, "current user" |
AddTransient | every time it's requested | small 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
IServiceScopeFactoryand 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:
appsettings.jsonappsettings.{Environment}.json, for exampleappsettings.Production.json- User secrets, in Development only (
dotnet user-secrets set ...) - Environment variables
- 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:
| Interface | Lifetime | Sees changes to config? |
|---|---|---|
IOptions<T> | singleton | no, it's read once |
IOptionsSnapshot<T> | scoped | yes, recomputed for each request |
IOptionsMonitor<T> | singleton | yes, 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:
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 inTIME_WAIT. Under load you run out of sockets ("socket exhaustion").- One static
HttpClientforever. Its connections never close, so it never sees DNS changes, for example during a failover. (SettingSocketsHttpHandler.PooledConnectionLifetimefixes 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:
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.
| Kind | AWS | Azure | Google Cloud | Other |
|---|---|---|---|---|
| Message queue | AmazonSQSClient (SQS) | ServiceBusClient (Service Bus) | PublisherClient, SubscriberClient (Pub/Sub) | RabbitMQ.Client, Confluent.Kafka |
| Object storage | AmazonS3Client (S3) | BlobServiceClient (Blob Storage) | StorageClient (Cloud Storage) | MinIO (speaks the S3 API) |
| Document database | AmazonDynamoDBClient (DynamoDB) | CosmosClient (Cosmos DB) | FirestoreDb (Firestore) | MongoDB.Driver |
| Secrets store | AmazonSecretsManagerClient | SecretClient (Key Vault) | SecretManagerServiceClient | VaultSharp (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 typedHttpClientinside 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 (useIOptionsMonitor<T>).- Secrets in
appsettings.jsoncommitted to git. Use user secrets locally, and a secrets store or workload identity in production. .Resultor.Wait()in startup code or in a hosted service'sStartAsync, which blocks the whole app from starting.- An endpoint that doesn't pass its
CancellationTokenon. - 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
- Configuration layers: merge settings layers the way
IConfigurationdoes, with__keys and sections. - Options validation: an
IValidateOptions<T>validator that reports every problem at startup. - Middleware pipeline: ASP.NET Core's
Use,RunandMapbuilt from delegates. - Retrying message handler: a real
DelegatingHandlerthat retries transient failures and honoursRetry-After. - DI container: singleton, scoped and transient lifetimes, disposal, and captive-dependency detection.
- 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