Modernizing ASP.NET Web Forms applications to Blazor using Porting Assistant for .NET

ASP.NET Web Forms has been a part of the .NET Framework since its initial release in 2002 and continues to power many web applications today. Customers want to modernize these applications to ASP.NET Core to realize cost savings, enhance performance, and increased agility.

However, the .NET team confirmed that Web Forms will not be ported to ASP.NET Core. This means Web Forms applications cannot take advantage of improvements made in .NET Core and later.

Blazor is a web UI framework that allows developer to use C#, both on the client and server side without requiring browser plugins. Blazor has a similar event-driven programming model and server-side hosting model as Web Forms, making for an easier transition to ASP.NET Core and is the recommended framework to use for Web Forms developers.

Porting Assistant for .NET is an open source analysis tool that reduces the manual effort and guesswork involved in porting .NET Framework applications to .NET Core 3.1, .NET 5, or .NET 6. It recently added support for porting ASP.NET Web Forms applications to Blazor on .NET Core 3.1 and later. Porting Assistant for .NET generates a compatibility assessment, suggests available replacements, and can apply conversions to your Web Forms projects to reduce the manual effort required to modernize to Blazor.

Porting Assistant for .NET is available as a standalone Windows application and also as a Visual Studio extension. It minimizes the effort required to port ASP.NET MVC to ASP.NET Core MVC and WCF to CoreWCF. Refer to the documentation to familiarize yourself with how to get started with Porting Assistant for .NET.

In this post, I showcase how to use the standalone version of Porting Assistant for .NET to modernize a Web Forms application to Blazor with the Web Forms starter project of eShopOnBlazor.

Prerequisites

For this tutorial, you should have:

• Developer machine with Visual Studio 2022
• Porting Assistant for .NET installed and configured. In this blog, I will be targeting conversion to .NET 6.0. You can change settings to your preferred target version.
• Sample ASP.NET Web Forms application from dotnet architecture GitHub samples.

Web Forms project code is in the src/eShopLegacyWebForms folder. The project that has been fully migrated to Blazor is in the src/eShopOnBlazor folder. Let us look at the high-level steps needed to complete the move to Blazor.

Overview of solution

Figure 1 – Porting steps overview

As you can see in Figure 1, the first step is to run an assessment of the solution. Once completed, you will be provided with a report you can use to get an overview of the level of effort needed to port to Blazor. Next, you will port the Web Forms project and Porting Assistant for .NET will apply multiple conversions to the project. We will deep dive into the conversions that Porting Assistant for .NET will execute automatically in the initial release of this feature. However, in the final step, developers will be required to make manual changes to complete the conversion. The suite of conversions Porting Assistant for .NET supports will continue to grow over time.

Let’s see the conversions in action.

Step 1: Run assessment

Once you’ve downloaded the eShopOnBlazor GitHub project, the first step is to run the assessment.

1. Launch the Porting Assistant. If this is your first time running the application, choose Get started to take you to the Assessed solutions list. Choose the Assess a new solution.
2. Select Choose file Navigate to, and open the eShopOnBlazor.sln file. Once the solution has been selected, select Assess.
3. Once the assessment is completed, you will see the banner message stating its completion. The assessed solutions list provides an overview of the project’s assessment, including projects that are already running .NET Core, incompatible NuGet packages, and APIs used by projects in the solution. Select the eShopOnBlazor solution, and choose View details to see the full assessment report.
   

   Figure 2 – Assessed solutions list showing eShopOnBlazor

4. The assessment dashboard provides similar information to the assessed solutions list.
   

   Figure 3 – Solution assessment dashboard

   Additionally, the assessment dashboard provides a set of tabs with additional details for the solution.

   

   Figure 4 – Assessment dashboard tabs

   The Projects tab provides an overview of the incompatible packages, APIs, porting status, among other data points. The Project references tab shows a graphical view of the package dependencies. The NuGet packages tab provides details of the compatible and incompatible dependencies, and suggested replacements if available. The APIs tab lists the incompatible APIs, what package they are in, and how many times they are referenced. The Source files tab lists all of the source files making up the projects in the application, with an indication of how many incompatible API calls can be found in each file.

5. Select the eShopLegacyWebForms project and choose View details
   

   Figure 5 – eShopOnBlazor Projects list

   This will display the assessment dashboard for the eShopLegacyWebForms project with similar details as shown for the eShopOnBlazor solution. In version 1.6.3, Porting Assistant does not assess code embedded in the markup (.aspx and .ascx files).

Step 2: Port project to .NET Core

With the assessment complete, you are ready to begin porting the Web Forms project to Blazor.

1. To begin the porting process, select Port project. By default, Porting Assistant will port the Web Forms project to Blazor.
2. When prompted to choose a location to save your ported project, select Modify source in place. If you cloned the GitHub project, this will allow you to easily see changes made by the porting process.
3. Once you choose Save, the port settings page will be displayed. You can take this opportunity to change the package versions to the latest versions available. You can also choose to skip this step, choose Port, and upgrade the NuGet packages using Visual Studio.
   

   Figure 6 – Port settings page

   The process may take a few minutes to finish, depending on the size of the project. After the porting is completed, you will see the eShopOnBlazor solution in the assessed solutions list.

   

   Figure 7 – Assessed solutions list post porting

   Let us review the automatic code changes made by the Porting Assistant to the project.

Configuration update

Porting Assistant will translate configuration elements of the root web.config file into .NET’s new appsettings.json format. Sections that do not apply to ASP.NET Core, such as system.webServer, are omitted. Currently, if a project contains more than one web.config file, translation for those will need to be done manually. See ASP.NET Core’s JSON configuration provider documentation for details.

Figure 8 – Web.config migration to appsettings.json

Static files migration

Static content files are moved to the wwwroot folder so that they can continue to be accessed via the same path. An excerpt is shown in Figure 9, using Visual Studio’s Git Changes window. Take care to validate that the porting process did not miss any files, or moved any additional files.

Figure 9 – Static content files migration

ASPX pages conversion

ASPX pages, including master pages, are converted into the Razor format. While this project does not contain user controls, Porting Assistant has some level of support for them. A best effort approach is taken when converting the associated code behind files. Items such as page lifecycle events, for whom Web Forms and Blazor are not fully compatible, should be validated manually.

Figure 10 – ASPX pages migration

Taking a closer look at some of the changes made to the markup, we can see that ASP:* controls have been converted to HTML 5 controls, or components from the Fritz.BlazorWebFormsComponents NuGet package.

Figure 11 – ASPX controls migration

If the markup cannot be converted, Porting Assistant will add comments in the files. For example, if a control, page directives, or one of its attributes is not supported, then comments are added as depicted in Figure 12.

Figure 12 – Page directives migration

Figure 13 – Unsupported control example

In the code behind files, supported page life cycle events have been converted and commented so that you know the original Web Forms page lifecycle event. Converted code should be validated to ensure that it continues to function as expected.

Figure 14 – Page life cycle event migration

ASP.NET Core’s startup process

Similar to what Porting Assistant’s support is for converting code behind files, the Global.asax will be converted to use the Startup class. Not all concepts from Web Forms can be translated to Blazor (for example, Session events) and so you will need to validate the changes made. In Figure 15, you can see how this project’s Global.asax was converted.

Figure 15 – Global.asax to Startup class migration

One item of note is that the eShopOnBlazor Web Forms project implemented the Application_BeginRequest lifecycle event. Porting Assistant translated this to ASP.NET Core middleware. This is a glimpse into Porting Assistant’s support for HTTP Modules and HTTP Handlers, as these, too, would be converted into ASP.NET Core middleware.

Additionally, configuration of dependency injection must be done manually. eShopOnBlazor uses Autofac and can be configured using the steps documented on their site. In Figure 15, you can see that the Porting Assistant added a comment stating as much.

So far, you have seen how the Porting Assistant for .NET automated to a certain extent the common steps needed to successfully migrate a Web Forms project to Blazor. This bootstraps and accelerates your migration process to Blazor.

Step 3: Complete manual changes

There are also few architectural changes between .NET Framework and .NET Core. Hence, any code converted by Porting Assistant should be validated for correctness. Additionally, in version 1.6.3, Porting Assistant does not provide support for the following steps:

Migrate runtime bundling and minification setup

Bundling and minification is a performance optimization technique used to minimize the number and file size downloaded by clients. ASP.NET Core does not provide a bundling and minification solution out of the box, but the open source project WebOptimizer provides a runtime solution, and projects such Gulp and Webpack provide a build time solution.

Model validation in Blazor

Blazor provides a similar experience as Web Forms for model validation when using the EditForm and Input* (for example, InputNumber and InputText) components. At this time, ASP:* controls , which provide some level of client-side validation. See the ASP.NET Core Blazor forms and validation page for more details on using Blazor components and annotations for validation.

Migrate data access

The advent of .NET Core also brought about Entity Framework Core (EF Core), but since Entity Framework 6 (EF 6) is supported in .NET, so your project is not required to migrate to EF Core. In a few cases, it may make sense to stay on EF 6. One such case is based on feature availability. While there is no direct upgrade path, you can use this helpful guide for porting EF 6 applications to EF Core.

Conclusion

In this blog post, I showcased how Porting Assistant for .NET can help you to accelerate modernizing your Web Forms application to Blazor. Porting Assistant for .NET continues to add functionalities to help customers modernize their different kinds of legacy .NET Framework applications to .NET Core, .NET 5 and .NET 6.

The Porting Assistant for .NET is free to use. To get started, install the standalone version or Visual Studio extension; refer to user guide. To learn how Porting Assistant can help with other use cases, check out the Migrating a Legacy .NET Framework Application to .NET 5 Using Porting Assistant for .NET video and the Modernizing legacy WCF applications to CoreWCF using Porting Assistant for .NET blog post.

Porting Assistant for .NET is made up of multiple open source projects, including the Porting Assistant for .NET SDK. We welcome community contributions. Whether it’s a new feature, bug report, correction, or additional documentation, we greatly value feedback and contributions from our community.

If you need support with modernizing your legacy .NET Framework applications using Porting Assistant for .NET, contact us at aws-porting-assistant-support@amazon.com.

AWS can help you assess how your company can get the most out of cloud. Join the millions of AWS customers that trust us to migrate and modernize their most important applications in the cloud. To learn more on modernizing Windows Server or SQL Server, visit Windows on AWS. Contact us to start your migration journey today.