Microservices in .NET

By the end of this lesson you'll be able to split a system into independent services along bounded contexts, choose synchronous (gRPC/HTTP) or asynchronous (message bus) communication for each link, make calls fault-tolerant with retries and circuit breakers, and reason about data ownership, observability, and Docker packaging — the real-world skills behind distributed .NET systems.

1. Service Boundaries — One Service per Bounded Context

The first and hardest decision is where to cut. Draw each boundary around a bounded context — a self-contained slice of the business with its own language and rules, like Orders, Inventory, or Shipping. A good boundary means a service can do its job using mostly its own data and change without forcing changes elsewhere. Crucially, a service owns its data: others see a contract (a message or an API response), never the raw tables. Read this worked example, run it, and notice how the services cooperate by passing a small record rather than sharing storage.

using System;

// Each microservice owns ONE bounded context — a slice of the business
// with its OWN data and its OWN rules. Services never reach into each
// other's tables; they talk only through contracts (messages or APIs).
class Program
{
    static void Main()
    {
        // Three independent services, each modelled here as a tiny class.
        var orders = new OrderService();
        var inventory = new InventoryService();
        var shipping = new ShippingService();

        // The
...

2. Communication — Synchronous vs Asynchronous

Services talk in two fundamentally different ways. Synchronous calls (gRPC or HTTP) are a phone call: you ask, you wait, you get an answer right now — great when you genuinely need the reply to continue, but the caller is blocked and coupled to the callee being up. Asynchronous messaging (a message bus) is dropping a letter in the post: you publish an event and move on, and interested services pick it up on their own time — slower to "complete" but far more decoupled and resilient. A good rule: query synchronously, react asynchronously.

Synchronous with gRPC. gRPC sends compact binary over HTTP/2 and generates strongly-typed clients from a .proto contract, so calling another service feels like calling a local method — and it's several times faster than JSON-over-HTTP. Here's the real shape of a gRPC server and client.

// ══════════════════════════════════════════════
// gRPC — fast, strongly-typed SYNC calls between services
// (real .NET code; needs Grpc.AspNetCore + a .proto file to run)
// ══════════════════════════════════════════════

// product.proto — the contract both client and server are generated from:
// syntax = "proto3";
// service ProductService {
//     rpc GetProduct (ProductRequest) returns (ProductReply);
// }
// message ProductRequest { int32 id = 1; }
// message ProductReply  { int32 id =
...

Asynchronous with a message bus. Before the real broker, model the essential idea in plain C#: a publisher builds an immutable message record (the DTO — Data Transfer Object — both sides agree on) and a consumer handles it. Finish the two blanks below.

using System;

// 🎯 YOUR TURN — model async messaging with a plain DTO (no broker needed).
// A 'publisher' builds a message record; a 'consumer' handles it. In real
// systems a message bus carries this record between two separate services.

// A message DTO is an IMMUTABLE record — the contract both sides agree on.
record OrderCreated(int OrderId, string CustomerEmail, decimal Total);

class Program
{
    static void Main()
    {
        // 1) PUBLISH: build the message the Order service woul
...

In a real system, MassTransit over RabbitMQ carries that record between two separately running services. The publisher fires an event and forgets it; any number of consumers subscribe without the publisher ever knowing they exist. That zero coupling is the superpower of async messaging.

// ══════════════════════════════════════════════
// MassTransit + RabbitMQ — ASYNC, decoupled messaging
// (real .NET code; needs MassTransit + a running broker to execute)
// ══════════════════════════════════════════════

using MassTransit;

// Shared contract — lives in a package both services reference.
public record OrderCreated(Guid OrderId, string Email, decimal Total);

// PUBLISHER — the Order service fires an event and forgets about it.
// It does NOT know or care who is listening. Ze
...

3. Resilience — Expect Every Call to Fail

Over a network, calls will fail — timeouts, blips, a service restarting. A resilient system absorbs that instead of crashing. A retry tries a transient failure again, ideally with growing delays (exponential backoff) so you don't hammer a struggling service. A circuit breaker watches the failure rate and, once it's too high, "opens" to stop calls for a while — letting a sick service recover instead of drowning it. A timeout caps how long you'll wait. First, build the core retry loop yourself; finish the three blanks.

using System;

// 🎯 YOUR TURN — finish the retry loop, then run it.
// A remote service is flaky: it fails the first 2 attempts, then succeeds.
// Real resilience (Polly) does exactly this — retry up to N times, then give up.
class Program
{
    static int _attempts = 0;

    static void Main()
    {
        int maxRetries = 3;        // try at most 3 times before giving up
        bool success = false;

        // 1) Loop from attempt 1 up to and including maxRetries.
        for (int attempt 
...

You'd never hand-write that in production — Polly (built into Microsoft.Extensions.Http.Resilience) gives you retry, circuit breaker, and timeout as a configured pipeline on your HttpClient. Notice how the consuming service catches the final failure and returns a fallback — graceful degradation — rather than letting one dead dependency take down the whole request.

// ══════════════════════════════════════════════
// Polly via Microsoft.Extensions.Http.Resilience
// retry + circuit breaker + timeout on an HttpClient
// (real .NET code; needs the resilience NuGet package to run)
// ══════════════════════════════════════════════

using Polly;

// Program.cs — every call through this client is now resilient.
builder.Services.AddHttpClient("products", c =>
    c.BaseAddress = new Uri("https://product-service:5001"))
  .AddResilienceHandler("pipeline", b =>
{
 
...

orders-service     ──▶  orders-db      (only orders-service connects)
inventory-service  ──▶  inventory-db   (only inventory-service connects)
shipping-service   ──▶  shipping-db    (only shipping-service connects)

// They share DATA via events/APIs — never a shared connection string.

4. Observability — Seeing Inside a Distributed System

In a monolith you read one log file. With a request hopping across five services, you need observability: the three pillars are logs (structured, searchable records of events), metrics (numbers over time — request rate, error rate, latency), and traces (one request's whole journey across services, tied together by a shared correlation id). .NET ships first-class support via ILogger for structured logging, OpenTelemetry for traces and metrics, and health checks so an orchestrator knows whether a service is alive.

// Structured logging — log VALUES, not pre-built strings, so they're queryable.
_logger.LogInformation("Order {OrderId} created for {Email}", id, email);

// OpenTelemetry — automatic distributed traces across HTTP and gRPC calls.
builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddAspNetCoreInstrumentation().AddHttpClientInstrumentation());

// Health checks — the orchestrator polls /health to decide if you're ready.
builder.Services.AddHealthChecks();
app.MapHealthChecks("/health");

5. Packaging with Docker

Each service ships as a container — your code plus exactly the runtime it needs, frozen into one image that runs identically on your laptop, in CI, and in production. That's what makes "deploy services independently" practical. A Dockerfile describes how to build the image; docker compose (or Kubernetes in production) runs the whole fleet together with its databases and message broker.

# Dockerfile — multi-stage: build with the SDK, run on the slim runtime.
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish OrderService -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:8.0       # smaller runtime-only image
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "OrderService.dll"]

# docker-compose.yml — run the services + their infrastructure together.
# services:
#   orders:    { build: ./OrderService,    ports: ["5001:8080"] }
#   inventory: { build: ./InventoryService, ports: ["5002:8080"] }
#   rabbitmq:  { image: rabbitmq:3-management }

using System;
using System.Collections.Generic;

// 🎯 MINI-CHALLENGE: a tiny in-memory message bus
// Model pub/sub with no broker — one service publishes, another handles.
//
// 1. Define a record PaymentReceived(int OrderId, decimal Amount).
// 2. In MessageBus:
//    - Keep a List of handlers:  List<Action<PaymentReceived>>
//    - Subscribe(handler): add the handler to the list.
//    - Publish(message): call EVERY subscribed handler with the message.
// 3. In Main:
//    - Create a bus.
//
...