Summary Prerequisites and limitations Architecture Tools Epics Related resources Additional information

Modernize ASP.NET Web Forms applications on AWS

Created by Vijai Anand Ramalingam (AWS) and Sreelaxmi Pai (AWS)

Environment: PoC or pilot	Technologies: Modernization; Containers & microservices; DevelopmentAndTesting; Web & mobile apps	Workload: Microsoft
AWS services: Amazon CloudWatch; Amazon ECS; AWS Systems Manager

Summary

This pattern describes the steps for modernizing a legacy, monolith ASP.NET Web Forms application by porting it to ASP.NET Core on AWS.

Porting ASP.NET Web Forms applications to ASP.NET Core helps you take advantage of the performance, cost savings, and robust ecosystem of Linux. However, it can be a significant manual effort. In this pattern, the legacy application is modernized incrementally by using a phased approach, and then containerized in the AWS Cloud.

Consider a legacy, monolith application for a shopping cart. Let’s assume that it was created as an ASP.NET Web Forms application and consists of .aspx pages with a code-behind (aspx.cs) file. The modernization process consists of these steps:

Break the monolith into microservices by using the appropriate decomposition patterns. For more information, see the guide Decomposing monoliths into microservices on the AWS Prescriptive Guidance website.
Port your legacy ASP.NET Web Forms (.NET Framework) application to ASP.NET Core in .NET 5 or later. In this pattern, you use Porting Assistant for .NET to scan your ASP.NET Web Forms application and identify incompatibilities with ASP.NET Core. This reduces the manual porting effort.
Redevelop the Web Forms UI layer by using React. This pattern doesn’t cover UI redevelopment. For instructions, see Create a New React App in the React documentation.
Redevelop the Web Forms code-behind file (business interface) as an ASP.NET Core web API. This pattern uses NDepend reports to help identify required files and dependencies.
Upgrade shared/common projects, such as Business Logic and Data Access, in your legacy application to .NET 5 or later by using Porting Assistant for .NET.
Add AWS services to complement your application. For example, you can use Amazon CloudWatch Logs to monitor, store, and access your application’s logs, and AWS Systems Manager to store your application settings.
Containerize the modernized ASP.NET Core application. This pattern creates a Docker file that targets Linux in Visual Studio and uses Docker Desktop to test it locally. This step assumes that your legacy application is already running on an on-premises or Amazon Elastic Compute Cloud (Amazon EC2) Windows instance. For more information, see the pattern Run an ASP.NET Core web API Docker container on an Amazon EC2 Linux instance.
Deploy the modernized ASP.NET core application to Amazon Elastic Container Service (Amazon ECS). This pattern doesn’t cover the deployment step. For instructions, see the Amazon ECS Workshop.

Note: This pattern doesn’t cover UI development, database modernization, or container deployment steps.

Prerequisites and limitations

Prerequisites

Visual Studio or Visual Studio Code, downloaded and installed.
Access to an AWS account using the AWS Management Console and the AWS Command Line Interface (AWS CLI) version 2. (See the instructions for configuring the AWS CLI.)
The AWS Toolkit for Visual Studio (see setup instructions).
Docker Desktop, downloaded and installed.
.NET SDK, downloaded and installed.
NDepend tool, downloaded and installed. To install the NDepend extension for Visual Studio, run NDepend.VisualStudioExtension.Installer (see instructions). You can select Visual Studio 2019 or 2022, depending on your requirements.
Porting Assistant for .NET, downloaded and installed.

Architecture

Modernizing the shopping cart application

The following diagram illustrates the modernization process for a legacy ASP.NET shopping cart application.

Modernizing a legacy shopping cart application

Target architecture

The following diagram illustrates the architecture of the modernized shopping cart application on AWS. ASP.NET Core web APIs are deployed to an Amazon ECS cluster. Logging and configuration services are provided by Amazon CloudWatch Logs and AWS Systems Manager.

Tools

AWS services

Amazon ECS – Amazon Elastic Container Service (Amazon ECS) is a highly scalable, fast container management service for running, stopping, and managing containers on a cluster. You can run your tasks and services on a serverless infrastructure that is managed by AWS Fargate. Alternatively, for more control over your infrastructure, you can run your tasks and services on a cluster of EC2 instances that you manage.
Amazon CloudWatch Logs – Amazon CloudWatch Logs centralizes the logs from all your systems, applications, and AWS services that you use. You can view and monitor the logs, search them for specific error codes or patterns, filter them based on specific fields, or archive them securely for future analysis.
AWS Systems Manager ─ AWS Systems Manager is an AWS service that you can use to view and control your infrastructure on AWS. Using the Systems Manager console, you can view operational data from multiple AWS services and automate operational tasks across your AWS resources. Systems Manager helps you maintain security and compliance by scanning your managed instances and reporting (or taking corrective action) on any policy violations it detects.

Tools

Visual Studio or Visual Studio Code – Tools for building .NET applications, web APIs, and other programs.
AWS Toolkit for Visual Studio – An extension for Visual Studio that helps develop, debug, and deploy .NET applications that use AWS services.
Docker Desktop – A tool that simplifies building and deploying containerized applications.
NDepend – An analyzer that monitors .NET code for dependencies, quality issues, and code changes.
Porting Assistant for .NET – An analysis tool that scans .NET code to identify incompatibilities with .NET Core and to estimate the migration effort.

Epics

Task Description Skills required

Task	Description	Skills required
Upgrade your.NET Framework legacy application to .NET 5.	You can use Porting Assistant for .NET to convert your legacy ASP.NET Web Forms application to .NET 5 or later. Follow the instructions in the Porting Assistant for .NET documentation.	App developer
Generate NDepend reports.	When you modernize your ASP.NET Web Forms application by decomposing it into microservices, you might not need all the .cs files from the legacy application. You can use NDepend to generate a report for any code-behind (.cs) file, to get all the callers and callees. This report helps you identify and use only the required files in your microservices. After you install NDepend (see the Prerequisites section), open the solution (.sln file) for your legacy application in Visual Studio and follow these steps: Build the legacy application in Visual Studio. On the Visual Studio menu bar, choose NDepend, Attach new NDepend project to current VS solution. Choose Analyze .NET assemblies. When analysis is complete, navigate to the project in Solution Explorer. Right-click any code-behind file (for example, `listproducts.aspx.cs`) that you want to generate the report for, and then choose Show on Dependency Graph. In the navigation bar, choose Callers and callees, and then choose Edit code query. In the Queries and Rules Edit pane, choose the download arrow, and then choose Export to Excel. This process generates a report for the code-behind file that lists all callers and callees. For more information about the dependency graph, see the NDepend documentation.	App developer
Create a new .NET 5 solution.	To create a new .NET 5 (or later) structure for your modernized ASP.NET Core web APIs: Open Visual Studio. Create a new, blank solution. Create new projects that target .NET 5 (or later), based on your legacy application. For examples of legacy and new projects for a shopping cart application, see the Additional information section. Use the NDepend report from the previous step to identify all required files. Copy these files from the application you upgraded earlier and add them to the new solution. Build the solution and fix all issues. For more information about creating projects and solutions, see the Visual Studio documentation. Note As you build the solution and verify functionality, you might identify several additional files to be added to the solution, in addition to the files that NDepend identified.	App developer

Upgrade your.NET Framework legacy application to .NET 5.

You can use Porting Assistant for .NET to convert your legacy ASP.NET Web Forms application to .NET 5 or later. Follow the instructions in the Porting Assistant for .NET documentation.

App developer

Generate NDepend reports.

When you modernize your ASP.NET Web Forms application by decomposing it into microservices, you might not need all the .cs files from the legacy application. You can use NDepend to generate a report for any code-behind (.cs) file, to get all the callers and callees. This report helps you identify and use only the required files in your microservices.

After you install NDepend (see the Prerequisites section), open the solution (.sln file) for your legacy application in Visual Studio and follow these steps:

Build the legacy application in Visual Studio.
On the Visual Studio menu bar, choose NDepend, Attach new NDepend project to current VS solution.
Choose Analyze .NET assemblies.
When analysis is complete, navigate to the project in Solution Explorer. Right-click any code-behind file (for example, listproducts.aspx.cs) that you want to generate the report for, and then choose Show on Dependency Graph.
In the navigation bar, choose Callers and callees, and then choose Edit code query.
In the Queries and Rules Edit pane, choose the download arrow, and then choose Export to Excel.

This process generates a report for the code-behind file that lists all callers and callees. For more information about the dependency graph, see the NDepend documentation.

App developer

Create a new .NET 5 solution.

To create a new .NET 5 (or later) structure for your modernized ASP.NET Core web APIs:

Open Visual Studio.
Create a new, blank solution.
Create new projects that target .NET 5 (or later), based on your legacy application. For examples of legacy and new projects for a shopping cart application, see the Additional information section.
Use the NDepend report from the previous step to identify all required files. Copy these files from the application you upgraded earlier and add them to the new solution.
Build the solution and fix all issues.

For more information about creating projects and solutions, see the Visual Studio documentation.

Note As you build the solution and verify functionality, you might identify several additional files to be added to the solution, in addition to the files that NDepend identified.

App developer

Task Description Skills required

Task	Description	Skills required
Implement web APIs with ASP.NET Core.	Let’s assume that one of the microservices that you identified in your legacy monolith shopping cart application is Products. You created a new ASP.NET Core web API project for Products in the previous epic. In this step, you identify and modernize all the web forms (.aspx pages) that are related to Products. Let’s assume that Products consists of four web forms, as illustrated earlier in the Architecture section: List Products View Product Add/Edit Product Delete Product You should analyze each web form, identify all the requests that are sent to the database to perform some logic, and get responses. You can implement each request as a web API endpoint. Given its web forms, Products can have the following possible endpoints: `/api/products` `/api/products/{id}` `/api/products/add` `/api/products/update/{id}` `/api/products/delete/{id}` As mentioned previously, you can also reuse all the other projects that you upgraded to .NET 5, including Business Logic, Data Access, and shared/common projects.	App developer
Configure Amazon CloudWatch Logs.	You can use Amazon CloudWatch Logs to monitor, store, and access your application’s logs. You can log data into Amazon CloudWatch Logs by using an AWS SDK. You can also integrate .NET applications with CloudWatch Logs by using popular .NET logging frameworks such as NLog, Log4Net, and ASP.NET Core logging framework. For more information about this step, see the blog post Amazon CloudWatch Logs and .NET Logging Frameworks.	App developer
Configure AWS Systems Manager Parameter Store.	You can use AWS Systems Manager Parameter Store to store application settings such as connection strings separately from your application’s code. The NuGet package Amazon.Extensions.Configuration.SystemsManager simplifies how your application loads these settings from the AWS Systems Manager Parameter Store into the .NET Core configuration system. For more information about this step, see the blog post .NET Core configuration provider for AWS Systems Manager.	App developer

Implement web APIs with ASP.NET Core.

Let’s assume that one of the microservices that you identified in your legacy monolith shopping cart application is Products. You created a new ASP.NET Core web API project for Products in the previous epic. In this step, you identify and modernize all the web forms (.aspx pages) that are related to Products. Let’s assume that Products consists of four web forms, as illustrated earlier in the Architecture section:

List Products
View Product
Add/Edit Product
Delete Product

You should analyze each web form, identify all the requests that are sent to the database to perform some logic, and get responses. You can implement each request as a web API endpoint. Given its web forms, Products can have the following possible endpoints:

/api/products
/api/products/{id}
/api/products/add
/api/products/update/{id}
/api/products/delete/{id}

As mentioned previously, you can also reuse all the other projects that you upgraded to .NET 5, including Business Logic, Data Access, and shared/common projects.

App developer

Configure Amazon CloudWatch Logs.

You can use Amazon CloudWatch Logs to monitor, store, and access your application’s logs. You can log data into Amazon CloudWatch Logs by using an AWS SDK. You can also integrate .NET applications with CloudWatch Logs by using popular .NET logging frameworks such as NLog, Log4Net, and ASP.NET Core logging framework.

For more information about this step, see the blog post Amazon CloudWatch Logs and .NET Logging Frameworks.

App developer

Configure AWS Systems Manager Parameter Store.

You can use AWS Systems Manager Parameter Store to store application settings such as connection strings separately from your application’s code. The NuGet package Amazon.Extensions.Configuration.SystemsManager simplifies how your application loads these settings from the AWS Systems Manager Parameter Store into the .NET Core configuration system.

For more information about this step, see the blog post .NET Core configuration provider for AWS Systems Manager.

App developer

Task	Description	Skills required
Use a shared cookie for authentication.	Modernizing a legacy monolith application is an iterative process and requires the monolith and its modernized version to co-exist. You can use a shared cookie to achieve seamless authentication between the two versions. The legacy ASP.NET application continues to validate user credentials and issues the cookie while the modernized ASP.NET Core application validates the cookie. For instructions and sample code, see the sample GitHub project.	App developer

Task

Description

Skills required

Use a shared cookie for authentication.

Modernizing a legacy monolith application is an iterative process and requires the monolith and its modernized version to co-exist. You can use a shared cookie to achieve seamless authentication between the two versions. The legacy ASP.NET application continues to validate user credentials and issues the cookie while the modernized ASP.NET Core application validates the cookie.

For instructions and sample code, see the sample GitHub project.

App developer

Task Description Skills required

Task	Description	Skills required
Create a Docker image by using Visual Studio.	In this step, you create a Docker file by using the Visual Studio for .NET Core web API. Open Visual Studio. In Solution Explorer, from the context (right-click) menu of your project, choose Add, Docker Support. Select Linux as the target operating system. Visual Studio creates a Docker file for your project. For a sample Docker file, see Visual Studio Container Tools for Docker on the Microsoft website.	App developer
Build and run the container by using Docker Desktop.	Now you can build, create and run the container in Docker Desktop. Open a Command Prompt window. Navigate to the solution folder where the Docker file is located. Run the following command to create the Docker image: `docker build -t aspnetcorewebapiimage -f Dockerfile .` Run the following command to view all Docker images: `docker images` Run the following command to create and run a container: `docker run -d -p 8080:80 --name aspnetcorewebapicontainer aspnetcorewebapiimage` Open Docker Desktop, and then choose Containers/Apps. You can see a new container named `aspnetcorewebapicontainer` running.	App developer

Create a Docker image by using Visual Studio.

In this step, you create a Docker file by using the Visual Studio for .NET Core web API.

Open Visual Studio.
In Solution Explorer, from the context (right-click) menu of your project, choose Add, Docker Support.
Select Linux as the target operating system.

Visual Studio creates a Docker file for your project. For a sample Docker file, see Visual Studio Container Tools for Docker on the Microsoft website.

App developer

Build and run the container by using Docker Desktop.

Now you can build, create and run the container in Docker Desktop.

Open a Command Prompt window. Navigate to the solution folder where the Docker file is located. Run the following command to create the Docker image:
```
docker build -t aspnetcorewebapiimage -f Dockerfile .
```
Run the following command to view all Docker images:
```
docker images
```

Run the following command to create and run a container:


docker run -d -p 8080:80 --name aspnetcorewebapicontainer aspnetcorewebapiimage

Open Docker Desktop, and then choose Containers/Apps. You can see a new container named aspnetcorewebapicontainer running.

App developer

Related resources

Run an ASP.NET Core web API Docker container on an Amazon EC2 Linux instance (AWS Prescriptive Guidance)
Amazon ECS Workshop
Perform ECS blue/green deployments through CodeDeploy using AWS CloudFormation (AWS CloudFormation documentation)
Getting started with NDepend (NDepend documentation)
Porting Assistant for .NET

Additional information

The following tables provide examples of sample projects for a legacy shopping cart application and the equivalent projects in your modernized ASP.NET Core application.

Legacy solution:

Project name	Project template	Target framework
Business Interface	Class Library	.NET Framework
BusinessLogic	Class Library	.NET Framework
WebApplication	ASP.NET Framework Web Application	.NET Framework
UnitTests	NUnit Test Project	.NET Framework
Shared ->Common	Class Library	.NET Framework
Shared ->Framework	Class Library	.NET Framework

New solution:

Project name	Project template	Target framework
BusinessLogic	Class Library	.NET 5.0
<WebAPI>	ASP.NET Core Web API	.NET 5.0
<WebAPI>.UnitTests	NUnit 3 Test Project	.NET 5.0
Shared ->Common	Class Library	.NET 5.0
Shared ->Framework	Class Library	.NET 5.0

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Manage on-premises container applications with Amazon ECS Anywhere

Run event-driven workloads with AWS Fargate