Many .NET teams start with a Modular Monolith.

Modular Monolith has clear boundaries between its modules. Modules can't access a database of other modules directly. Modules can talk with each other only via a public API. This works exactly as in microservices, but in a single Application.

But as the system grows, you may need to scale modules independently, introduce load balancing, and move to a microservices architecture.

Migrating from a Modular Monolith to microservices is a natural evolution for many projects, but it requires careful planning and execution.

If you simply split the code into multiple projects, you'll end up with a distributed monolith — harder to maintain than before.

Today, I will show you a step-by-step migration strategy for transforming a Modular Monolith in .NET into a well-structured microservices architecture.

During migration, we will do the following steps:

1. Define Service Boundaries
2. Extract modules into independent services
3. Replace direct module-to-module calls with service REST APIs
4. Introduce asynchronous messaging for decoupling
5. Add Observability with OpenTelemetry
6. Introduce an API Gateway

Let's dive in.

Let's explore Modular Monolith with three modules: Shipments, Carriers, and Stocks.

Each module is built using a combination of Vertical Slice Architecture and Clean Architecture, which structures an application by features. Each slice encapsulates all aspects of a specific feature, including the API, business logic, and data access.

Here is a project's structure:

You can download the source code of this Modular Monolith from my previous article.

Now let's see how we can migrate it to microservices.

The first step in moving from a modular monolith to microservices is deciding where the service boundaries should be. Without clear boundaries, you risk ending up with "distributed monolith" — services that depend on each other too much.

Defining service boundaries is a challenging task. It's difficult to get it right the first time, and it takes time to understand the business domain and the dependencies between modules.

That's why many teams choose to start with a Modular Monolith, as it's much easier to adjust module boundaries within a single solution.

If you use a Domain-Driven Design (DDD) approach in a Modular Monolith, you can define boundaries by defining bounded contexts. Each bounded context is a clear business or technical area where terms, rules, and logic make sense together.

Once you have a Modular Monolith, you can start to identify the boundaries between services.

As a starting point, you can extract the modules into their own services. However, some modules can sometimes be combined into a single service.

In our Modular Monolith, we have three Modules:

• Shipments Module: Handles creating orders for shipments.
• Carriers Module: Maintains information about shipping partners and registers shipments for delivery.
• Stocks Module: Manages product inventory levels.

Each module exposes an interface that allows other modules to call it. Under the hood, it's a method call in the same process.

Let's briefly explore how modules communicate with each other.

The most complex use case is "Create Shipment". It involves communication with the Carriers and Stocks modules:

1. Checks if a Shipment for a given OrderId is already created
2. Calls the Stocks Module to check the products' availability
3. Creates a Shipment in the database
4. Calls the Carrier Module to save the shipment details
5. Calls the Stocks Module to update stock levels

In this application, we can extract Shipments, Carriers, and Stocks modules into their own services.

Once we have defined our service boundaries, the next step is to separate them physically. The goal here is not yet to deploy each service independently, but to prepare your system for that future step.

At first, you don't need to create separate GIT repositories for every service.

Instead, extract each module into its own service project inside the same solution. This lets you:

• Keep the migration safe and manageable.
• Avoid breaking changes across teams too early.
• Still share common infrastructure (logging, configuration) until you are ready for a full split.

Why not split everything at once?

If you immediately create separate repositories and databases, you'll increase complexity too fast. Things like CI/CD pipelines and deployment will need to be addressed immediately.

We don't need this complexity right now. We can start with a single solution and gradually split it into multiple services.

In a Modular Monolith, each module consists of the following projects:

• Domain: Contains the domain model, business logic, and shared interfaces.
• Infrastructure: Contains infrastructure-specific code, like database configuration, authentication.
• Features: Contains the application logic.
• PublicApi: Contains the public API contracts for module communication.

And we have one runnable Host project that starts the application.

When splitting to microservices, we need to do the following steps for each service:

• Extract all the Common logic into separate projects
• Leave the Domain, Infrastructure and Features projects as-is
• Create a new ASP.NET Core Web API project to run the service

Here is what our project should look like after completing these steps:

Here is what the ShipmentService.Host project looks like:

The Program.cs is as simple as this:

csharp
1using Common.Infrastructure.Database;
2using ShipmentService.Host.Middlewares;
3using ShipmentService.Host.Seeding;
4
5var builder = WebApplication.CreateBuilder(args);
6
7builder.Services.AddWebHostDependencies();
8
9builder.AddCoreHostLogging();
10builder.Services.AddCoreWebApiInfrastructure();
11
12builder.Services
13    .AddCoreInfrastructure(builder.Configuration, ShipmentServiceRegistration.ActivityServiceName)
14    .AddShipmentService(builder.Configuration);
15
16// Seed entities in DEVELOPMENT mode
17if (builder.Environment.IsDevelopment())
18{
19    builder.Services.AddScoped<SeedService>();
20}
21
22var app = builder.Build();
23
24// Run migrations in DEVELOPMENT mode
25if (app.Environment.IsDevelopment())
26{
27    using var scope = app.Services.CreateScope();
28    await scope.MigrateServiceDatabasesAsync();
29
30    var seedService = scope.ServiceProvider.GetRequiredService<SeedService>();
31    await seedService.SeedDataAsync();
32}
33
34if (app.Environment.IsDevelopment())
35{
36    app.UseSwagger();
37    app.UseSwaggerUI();
38}
39
40app.UseAuthentication();
41app.UseAuthorization();
42
43app.MapApiEndpoints();
44
45await app.RunAsync();

In our Modular Monolith, modules usually communicate through direct method calls in the same process.

Once you split modules into services, you need to replace these calls with service-to-service communication.

You have two options: synchronous APIs (using HTTP or gRPC) or asynchronous messaging (via events).

I will suggest the following migration strategy:

• Replace method calls with synchronous APIs (HTTP or gRPC).
• Replace in-memory events with a message bus.

Start with synchronous APIs (HTTP or gRPC). These are easier to introduce since they feel closer to the direct method calls we are replacing. Gradually introduce asynchronous messaging as needed.

In our Modular Monolith, the Stocks Module exposes an API in the Modules.Stocks.PublicApi project:

csharp
1public interface IStockModuleApi
2{
3    Task<CheckStockResponse> CheckStockAsync(
4        CheckStockRequest request, 
5        CancellationToken cancellationToken = default);
6    
7    Task<UpdateStockResponse> UpdateStockAsync(
8        UpdateStockRequest request,
9        CancellationToken cancellationToken = default);
10}

In the Stocks service, instead of a class that implements the IStockModuleApi interface, we have to expose a Web API (Minimal API endpoint):

csharp
1public class CheckStockApiEndpoint : IApiEndpoint
2{
3    public void MapEndpoint(WebApplication app)
4    {
5       app.MapPost(RouteConsts.CheckStock, Handle);
6    }
7
8    private static async Task<IResult> Handle(
9       [FromBody] CheckStockRequest request,
10       IValidator<CheckStockRequest> validator,
11       ICheckStockHandler handler,
12       CancellationToken cancellationToken)
13    {
14       var validationResult = await validator.ValidateAsync(request, cancellationToken);
15       if (!validationResult.IsValid)
16       {
17          return Results.ValidationProblem(validationResult.ToDictionary());
18       }
19
20       var response = await handler.HandleAsync(request, cancellationToken);
21       if (response.IsError)
22       {
23          return response.Errors.ToProblem();
24       }
25
26       return Results.Ok(response.Value);
27    }
28}

We can now replace direct calls to the Stock Module with a synchronous HTTP API.

We will use Refit library to generate the client code. This library provides an interface wrapper (with code generation) that wraps Typed HttpClient using HttpClientFactory.

csharp
1public interface IStockServiceApi
2{
3    [Post("/api/stocks/check")]
4    Task<ApiResponse<Result<Success>>> CheckStockAsync(
5        CheckStockRequest request,
6        CancellationToken cancellationToken);
7}

Here is how we register the Refit client in DI:

csharp
1var stockApiBaseUrl = configuration["StockService:BaseUrl"]!;
2
3services.AddRefitClient<IStockServiceApi>()
4    .ConfigureHttpClient(c => c.BaseAddress = new Uri(stockApiBaseUrl));

The best part is that our CreateShipmentHandler remains unchanged and only needs to call the Refit IStockServiceApi interface instead of the old IStockModuleApi interface.

csharp
1internal sealed class CreateShipmentHandler(
2    ShipmentsDbContext context,
3    IStockServiceApi stockApi,
4    ILogger<CreateShipmentHandler> logger)
5    : ICreateShipmentHandler
6{
7    public async Task<ErrorOr<ShipmentResponse>> HandleAsync(
8        CreateShipmentRequest request,
9        CancellationToken cancellationToken)
10    {
11        var stockRequest = CreateCheckStockRequest(request);
12
13        var stockResponse = await stockApi.CheckStockAsync(stockRequest, cancellationToken);
14        if (!stockResponse.IsSuccess)
15        {
16             logger.LogInformation("Stock check failed: {ErrorMessage}", stockResponse.ErrorMessage);
17            return Error.Validation("ProductsNotAvailableInStock", stockResponse.ErrorMessage ?? "Products not available in stock");
18        }
19        
20        // ...
21}

Now let's replace the UpdateStockAsync method with an asynchronous HTTP API.

Your modular Monolith likely raises in-memory events that trigger handlers inside the same process. To decouple services, move those integration events into a message queue or event bus.

Also, you can replace some direct method calls with asynchronous messaging.

Instead of the Shipment service calling Stocks directly every time, Shipment service can publish a ShipmentCreatedEvent event.

Stocks Service (and any other interested service) subscribes to and reacts to this event.

Why asynchronous messaging?

• Loose coupling: Publishers don't know who listens. You can add or remove consumers without changing publishers.
• Resilience: Temporary outages don't break the whole flow. Messages wait in a queue or topic until consumers catch up with them.
• Scalability: Each service scales based on its own load. A busy consumer can scale out horizontally to read the queue.

I will define the ShipmentCreatedEvent in the ShipmentService.PublicApi project:

csharp
1public sealed record ShipmentCreatedEvent(Guid Id, List<ShipmentProduct> Products);
2
3public sealed record ShipmentProduct(string Product, int Quantity);

We will use MassTransit library and RabbitMQ to implement the producing and consuming of events:

csharp
1internal sealed class CreateShipmentHandler(
2    ShipmentsDbContext context,
3    IStockServiceApi stockApi,
4    IEventPublisher eventPublisher,
5    ILogger<CreateShipmentHandler> logger)
6    : ICreateShipmentHandler
7{
8    public async Task<ErrorOr<ShipmentResponse>> HandleAsync(
9        CreateShipmentRequest request,
10        CancellationToken cancellationToken)
11    {
12        // ...
13        
14        await context.Shipments.AddAsync(shipment, cancellationToken);
15        await context.SaveChangesAsync(cancellationToken);
16        
17        var shipmentCreatedEvent = new ShipmentCreatedEvent(shipment.Id, products);
18
19        await publishEndpoint.Publish(shipmentCreatedEvent, cancellationToken);
20
21        return shipment.MapToResponse();
22    }
23}

In the Stocks service, we need to define a Consumer for the ShipmentCreatedEvent:

csharp
1public class ShipmentCreatedConsumer(
2    ILogger<ShipmentCreatedConsumer> logger,
3    IDecreaseStockHandler decreaseStockHandler)
4    : IConsumer<ShipmentCreatedEvent>
5{
6    public async Task Consume(ConsumeContext<ShipmentCreatedEvent> context)
7    {
8       var message = context.Message;
9
10       logger.LogInformation("Received shipment created event: {@Event}", message);
11
12       var products = message.Products.Select(x => new ProductStock(x.Product, x.Quantity)).ToList();
13       var request = new DecreaseStockRequest(products);
14
15       await decreaseStockHandler.HandleAsync(request, context.CancellationToken);
16    }
17}

Learn more about how to work with MassTransit in this article.

Once services communicate over HTTP and RabbitMQ, troubleshooting becomes more challenging.

OpenTelemetry opens the light into what is happening in your application. It provides a standardized way to collect and analyze telemetry data from your applications, giving you visibility into their behavior.

OpenTelemetry is essential for monitoring any application, from large microservices to monoliths. Yes, even in monoliths, you can benefit from OpenTelemetry.

Our application has the following external dependencies:

• Postgres database
• RabbitMQ

And we also need to monitor our own services:

• Shipment Service
• Carrier Service
• Stocks Service

Monitoring these dependencies and services is crucial for understanding how your application performs and interacts with the rest of the system.

If your Modular Monolith is already using OpenTelemetry, you can skip this step.

First, we need to add the following NuGet packages:

csharp
1dotnet add package Npgsql.OpenTelemetry
2dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
3dotnet add package OpenTelemetry.Extensions.Hosting
4dotnet add package OpenTelemetry.Instrumentation.AspNetCore
5dotnet add package OpenTelemetry.Instrumentation.Http
6dotnet add package OpenTelemetry.Instrumentation.Runtime

To configure tracing, you need to add OpenTelemetry to DI:

csharp
1private static IServiceCollection AddHostOpenTelemetry(
2    this IServiceCollection services,
3    string serviceName)
4{
5    services
6        .AddOpenTelemetry()
7        .ConfigureResource(resource => resource.AddService(serviceName))
8        .WithTracing(tracing =>
9        {
10            tracing
11                .AddAspNetCoreInstrumentation()
12                .AddHttpClientInstrumentation()
13                .AddNpgsql()
14                .AddSource(MassTransit.Logging.DiagnosticHeaders.DefaultListenerName);
15
16            tracing.AddOtlpExporter();
17        });
18
19    return services;
20}

You can send telemetry data to your backend systems by configuring exporters.

You can check my article for a complete guide on how to configure OpenTelemetry with Jaeger and Seq.

Here is how the services interact with each other when creating a shipment (Seq):

We have split our Monolith into services, which communicate with each other over HTTP and RabbitMQ.

But we have to hardcode the routes for each service. We also need to update the routes in each dependent service when we migrate services to new hosts.

We need to introduce an API Gateway that sits in front of our services, giving a single endpoint for communication.

We will create a new ASP.NET Core Web API project that will act as an API Gateway. We will use Yarp as an API Gateway.

Yarp is a reverse proxy that can route requests to multiple services. It can also handle authentication, authorization, and load balancing.

Yarp is very performant and has the best integration with the ASP.NET Core ecosystem.

You need to add the following NuGet package to the API Gateway project:

csharp
1dotnet add package Yarp.ReverseProxy

In the appsettings.json, we need to configure the routes for each service:

json
1{
2  "ReverseProxy": {
3    "Routes": {
4      "stock-service-route": {
5        "ClusterId": "stock-service-cluster",
6        "Timeout": "00:00:30",
7        "Match": {
8          "Path": "/api/stocks/{**catch-all}"
9        }
10      },
11      "shipment-service-route": {
12        "ClusterId": "shipment-service-cluster",
13        "Timeout": "00:00:30",
14        "Match": {
15          "Path": "/api/shipments/{**catch-all}"
16        }
17      }
18    },
19    "Clusters": {
20      "stock-service-cluster": {
21        "HttpClient": {
22          "MaxConnectionsPerServer": 500
23        },
24        "Destinations": {
25          "destination1": {
26            "Address": "http://stock-service:8080"
27          }
28        }
29      },
30      "shipment-service-cluster": {
31        "HttpClient": {
32          "MaxConnectionsPerServer": 500
33        },
34        "Destinations": {
35          "destination1": {
36            "Address": "http://shipment-service:8080"
37          }
38        }
39      }
40    }
41  }
42}

Here I have specified the routes for the StockService and ShipmentService in the Docker containers:

yml
1services:
2  shipping-api-gateway:
3    image: shipping-api-gateway
4    container_name: shipping-api-gateway
5    build:
6      context: .
7      dockerfile: ./Shipping.Gateway.Host/Dockerfile
8    ports:
9      - "5000:8080"
10    environment:
11      - ASPNETCORE_ENVIRONMENT=Production
12    restart: always
13    networks:
14      - docker-web
15  
16  shipment-service:
17    image: shipment-service
18    container_name: shipment-service
19    build:
20      context: .
21      dockerfile: ./Shipments/ShipmentService.Host/Dockerfile
22    ports:
23      - "5005:8080"
24    environment:
25      - ASPNETCORE_ENVIRONMENT=Production
26    restart: always
27    networks:
28      - docker-web
29
30  stock-service:
31    image: stock-service
32    container_name: stock-service
33    build:
34      context: .
35      dockerfile: ./Stocks/StockService.Host/Dockerfile
36    ports:
37      - "5152:8080"
38    environment:
39      - ASPNETCORE_ENVIRONMENT=Production
40    restart: always
41    networks:
42      - docker-web
43    
44networks:
45  docker-web:
46    driver: bridge
47

For local development, you can use the actual ports for each service in appsettings.Development.json when running all the services from the IDE.

Now that your API Gateway setup is ready, let's register the necessary services in DI in the Program.cs:

csharp
1var builder = WebApplication.CreateBuilder(args);
2
3// Register Yarp services
4builder.Services.AddRequestTimeouts();
5
6builder.Services.AddReverseProxy()
7    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));
8
9builder.Services
10    .AddOpenTelemetry()
11    .ConfigureResource(resource => resource.AddService("shipping-gateway"))
12    .WithTracing(tracing =>
13    {
14       tracing
15          .AddAspNetCoreInstrumentation()
16          .AddHttpClientInstrumentation()
17          .AddSource("Yarp.ReverseProxy");
18
19       tracing.AddOtlpExporter();
20    });
21
22var app = builder.Build();
23
24app.UseRequestTimeouts();
25
26app.MapReverseProxy();
27
28await app.RunAsync();

Note: I use OpenTelemetry to trace the requests to the API Gateway (as you can see in the previous screenshot).

We have migrated our Modular Monolith to Microservices in a single solution. All services are running in Docker containers and communicate over HTTP and RabbitMQ.

We have added OpenTelemetry and Yarp API Gateway as a single entry point for all services.

However, there are additional things to consider:

• Move Services to their own GIT repositories; extract Public shared contracts into versioned NuGet packages
• Introduce CI/CD for each service
• Implement Health Checks for each service
• Integrate Authorization services and propagate tokens across downstream calls
• Implement outbox/inbox patterns for messaging
• Implement idempotency in services as needed
• Add resilience policies (retries, timeouts, circuit breakers, fallbacks) and verify with load tests
• Add distributed caching as needed
• Write Integration tests for each Service
• Write Load tests to test your system under load

Hope you find this newsletter useful. See you next time.