Microsoft Workloads on AWS

Modernizing .NET Applications to Microservices using AWS Migration Hub Refactor Spaces

In this blog, we’ll dive into how to effectively use AWS Migration Hub Refactor Spaces for modernizing legacy .NET Framework monolithic applications to a microservices based architecture. Refactoring can bring many benefits, but may come with challenges such as compatibility issues, addressing existing technical debt, and integration with modern systems.

However, with the right approach, it’s possible to make this process smooth and reduce risk. One such approach is to use a technique called the “Strangler Fig Pattern” to incrementally migrate monolithic applications to a microservices-based architecture. This strategy helps developers transition monolithic applications to be more scalable, agile, and cost-effective, while minimizing risk and avoiding downtime.

Migration Hub Refactor Spaces is a service that helps developers use the strangler fig pattern to build and deploy microservices to AWS. This reduces the risk of disruption compared with refactoring the entire monolithic application all at once. It simplifies the modernization process by providing a set of pre-built tools, services, and integrations that make it easier to refactor legacy applications on AWS.

Migration Hub Refactor Spaces

AWS Migration Hub Refactor Spaces can be used as the starting point for modernizing your monolithic .NET applications to microservices. Using Migration Hub Refactor Spaces helps reduce the undifferentiated heavy lifting of building and operating the infrastructure needed to perform the incremental refactoring. It also helps reduce your risk when transforming applications into microservices or adding new microservices capabilities to applications. For a deep dive on the entire Migration Hub Refactor Spaces service, review the AWS Migration Hub Refactor Spaces Environment blog post.

Migration Hub Refactor Spaces Environment Overview

Figure 1: Migration Hub Refactor Spaces Environment Overview

A Migration Hub Refactor Spaces service provides an environment that is made up of one or more AWS accounts. Using multiple accounts with microservices allows distinct security controls to be applied to individual services, allows fine grained cost control, and helps with rate limiting of the services. Refer to the benefits of using multiple AWS accounts for other advantages of a multi-account strategy.

An environment provides the infrastructure, multi-account networking, and routing that you need to modernize incrementally (Figure 1). With Migration Hub Refactor Spaces environments, you can add new microservices to an external HTTPS endpoint and incrementally route traffic to them. Migration Hub Refactor Spaces bridges networking across AWS accounts so that legacy and new services can communicate.

Migration Hub Refactor Spaces creates these resources in the accounts configured. This gives you the flexibility to apply your own configurations to them, such as Amazon API Gateway custom domains, after Migration Hub Refactor Spaces creates them.

A Migration Hub Refactor Spaces application orchestrates an Amazon API Gateway, Network Load Balancer, and resource-based AWS Identity and Access Management (IAM) policies so that you can easily add new services to an external HTTPS endpoint.

The architecture in Figure 2 shows the resources provisioned when you create a Migration Hub Refactor Spaces environment. The following resources are provisioned automatically.

Migration Hub Refactor Spaces Environment Resources Provisioned

Figure 2: Migration Hub Refactor Spaces Environment Resources Provisioned

To route traffic to the new services incrementally, you can also register a new domain name as a hosted zone in Amazon Route 53. Migration Hub Refactor Spaces periodically resolves Domain Name System (DNS) entries for these services. This keeps underlying architecture changes hidden from your application consumers.

Microservices with .NET applications

ASP.NET applications are good candidates to use with Migration Hub Refactor Spaces to incrementally modernize to microservices. Examples are:

  • NET Web API – These return data only using HTTP/HTTPS. They are often used as API backends, and you can extract different APIs into microservices and routes in Refactor Spaces.
  • NET MVC (Model, View, Controller) – These are more commonly used for developing UI-oriented web applications that use views to display data. You can extract individual controllers into microservices with Migration Hub Refactor Spaces.

Note that Migration Hub Refactor spaces is not exclusively used for breaking monolithic applications into microservices. You could also use it to add new functionality to existing applications, or during the process of porting from older versions of .NET Framework to the latest version of modern .NET.

Figure 3 shows the Swagger UI for a simple ASP.NET Web API application with two controllers for Payment and Shopping. Each controller has different actions such as Get, Put, and Delete that can be called via a URL. ASP.NET Web API applications are simpler than MVC applications to refactor to microservices since they do not have any views that require more substantial code refactoring.

Figure 3: Swagger View of a Basic ASP.NET Web API

Figure 4 shows the architecture for one of the ways such an application can be deployed on AWS. Web traffic goes through an Application Load Balancer (ALB), and is then passed to the Amazon EC2 instances hosting the ASP.NET application, and data is stored on SQL Server, a common database used with .NET applications.

Figure 4: Simple ASP.NET Web API Architecture on AWS

For this application, we will consider how to deploy the Shopping controller as a new microservice using AWS Fargate with ECS and Linux containers and Amazon Aurora PostgreSQL.

You can use the assistive AWS Microservices Extractor for .NET tool to help identify and extract specific code for your microservices.

Using Migration Hub Refactor Spaces with .NET Applications

This section will walk through taking the simple ASP.NET application hosted in AWS Elastic Beanstalk (Figure 4) and host the Shopping components as a new microservice on AWS Fargate as a container.

Setting up the Environment

The first step is to set up an environment in Refactor Spaces. To do this, navigate to the AWS Migration Hub Console in your AWS account. You can also enter “Migration Hub” in the search box (Figure 5).

Figure 5: Search for the Migration Hub service in the AWS console.

  1. On the left menu, choose Refactor Spaces.
  2. On the Refactor Spaces page, choose Environments in the App Refactor
  3. To create an environment, choose Create Environment..
  4. On the Create environment page, enter a name in the Environment name Leave the rest of the values as their defaults. Choose Next.
  5. On the Create application page, enter an application name in the Name Then, in the Proxy settings section, choose Create VPC (Figure 6). This will let Refactor Spaces use a single endpoint to route traffic to the different application services.

Figure 6:Application proxy settings

  1. On the Create a VPC page, select “VPC and more” for Resources to create. Enter a value for Name tag auto-generation, which will help you easily identify the VPC, and enter an IPv4 CIDR range for the proxy VPC.Select “None” for VPC endpoints. Leave the rest of the values as their defaults (Figure 7). Choose Create VPC.

Figure 7: Create Proxy VPC

  1. When the VPC has been created, return to the Refactor Spaces setup page and select the VPC from the Proxy VPC Choose Next.
  2. On the Share environment page, leave the values as the defaults and choose
  3. On the Review page, validate all the settings and choose Create environment.

You can also view the instructions for detailed steps on how to setup environments.

Once the environment is created, you can view information about it on its details page. Choose Environments on the side menu, and find your environment in the list. Check radio button next to your environment and choose View details (Figure 8).

Figure 8: View the details about your environment.

The details page shows a summary of your environment. You can find the applications in your environment, as well as other information such as networking, and information about the services.

The Health status field should indicate that the environment is healthy. There will be one application listed under applications, which should also be in a healthy state.

Setting up the Services

Services provide the application’s business capabilities. Your existing application is represented by one or more services. Each service has an endpoint (either an HTTP/HTTPS URL or an AWS Lambda function). It does not matter where you host these services as long as there is an endpoint that is reachable. In this walkthrough the monolithic service will be deployed to AWS Fargate.

  1. Select the radio button next to your application, and choose Create Service (Figure 9).

Figure 9: Create Application.

  1. Enter a value for Service name.
  2. Enter the endpoint for your existing application. For example, if the application is deployed to Elastic Beanstalk, insert its endpoint and optionally enter a health check endpoint if your application supports it.
  3. Once configured, choose Create Service.

Repeat these steps add each microservice as a service to your Refactor Spaces application. For example (Figure 10), a Shopping Cart microservice has been deployed to AWS Fargate and added to the application.

Figure 10: Shopping cart microservice

Once both services have been deployed you can create a route to send requests for the shopping cart to the new microservice. Routes define which service and path requests will be routed to. In this example (Figure 11), there is a default route to the monolithic application, plus a route indicating that   requests to /api/Shopping will be routed to the new service. If you were to deactivate this route then all requests would be routed to the monolithic application.

Figure 11: Service routes for main application and shopping cart

By retrieving the proxy URL for the application in the Proxy section you can test this (Figure 12).

Figure 12: Monolithic application test

Accessing the /api/Shopping path routes to the monolith, since the new route to the Microservice is active (Figure 13).

Figure 13: Test the microservice route

If there are any issues with the new microservice, you can immediately disable routing to it, and revert all traffic to the monolith by deactivating the route from the Refactor Spaces application console.

Microservices Architecture

After setting up Refactor Spaces application architecture will resemble Figure 14, with two AWS accounts – one hosting the original monolithic application and another hosting the new microservice application. Each has an application load balancer in which traffic is routed from the AWS Transit Gateway. he monolithic instance is still online and can be accessed via the application load balancer, but now with the new microservice for Payment running separately.

Figure 14: Payment route to new microservice

Migration Hub Refactor Spaces will automatically route traffic sent to the payment endpoints to the payments microservice while routing all other traffic to the monolithic instance. The routes can be disabled at any time to reroute traffic back to the monolith. This is important and useful if there are issues with the new microservices, mitigating risks by allowing traffic to quickly be redirected back to the original monolith.

Clean Up

If you would like to delete your Refactor Spaces environment, you will first need to delete the routes, services, and applications within the environment. Once the environment is deleted, the resources provisioned by Refactor Spaces (such as the Transit Gateway, Network Load Balancer, and API Gateway API) are also deleted. Additionally, the VPC that was created in Step 5 of Setting Up the Environment.


When moving to a microservices-based application architecture, many iterations may be required. By using AWS Migration Hub Refactor spaces, you can reduce the risk and effort by running your monolith and managing the access via routes. As you build and add new microservices, you can then seamlessly transition requests between the legacy application and the modernized services. AWS Migration Hub Refactor Spaces can be used as you gradually modernize an application to use microservices, including if you want to incrementally port an application to a newer version of .NET. AWS provides the Porting Assistant for .NET and the AWS Toolkit for .NET Refactoring that can be used with Migration Hub Refactor Spaces. AWS also provides the AWS Microservices Extractor for .NET to help identify and extracting microservices. Finally before starting any modernization solution, it is important to create a modernization plan. For more details on this, refer to Strategy for modernizing applications in the AWS Cloud .

AWS has significantly more services, and more features within those services, than any other cloud provider, making it faster, easier, and more cost effective to move your existing applications to the cloud and build nearly anything you can imagine. Give your Microsoft applications the infrastructure they need to drive the business outcomes you want. Visit our .NET on AWS and AWS Database blogs for additional guidance and options for your Microsoft workloads. Contact us to start your migration and modernization journey today.

Stephen Foy

Stephen Foy

Stephen is a Specialist Solutions Architect with over 15 years experience as a .NET developer, he deep focus in modernizing workloads for AWS. With expertise across various technologies such as SQL Server, Windows, Game Technology and more.

Jay Shin

Jay Shin

Jay is a Database Migration Specialist in DMA (Database Migration Accelerator), based out of Singapore, where she is responsible for accelerating customers’ database migration and modernisation with Cloud native database services.