Microsoft & .NETASPTip for Porting Legacy ASP.NET Apps to ASP.NET Core

Tip for Porting Legacy ASP.NET Apps to ASP.NET Core content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

ASP.NET has for long been a popular Web application development framework since it was released in 2002. However, Web development using legacy ASP.NET has been Windows-centric. With a view to expand this reach to multiple operating systems, Microsoft released .NET Core. ASP.NET Core is a Web application development framework that runs on top of .NET Core.

Incidentally, Microsoft released .NET Core 1.0, ASP.NET Core 1.0, and Entity Framework Core 1.0 in June, 2016. This release marks the beginning of a new era—a beginning of an era that promises to enable Web application developers to build applications that can target multiple operating systems.

ASP.NET Core is a significant redesign of the legacy ASP.NET framework and has already become widely popular. ASP.NET Core is a lean, composable, Open Source framework that you can leverage to build Web and Cloud applications. ASP.NET Core is cross-platform—it is available on the Windows, Linux, and Mac platforms. This article discusses the strategies that can be adopted to migrate ASP.NET applications to ASP.NET Core.

Migrating to ASP.NET Core

The most important thing you should consider when migrating your legacy ASP.NET application to ASP.NET Core is the changes that are needed in your code due to compatibility reasons. I’ve discussed a tool later in this article that would help you a lot in analyzing the changes needed. You should create a list of the BCL references and dependencies that need to be changed if they are not supported in .NET Core. Note that .NET Core is just a subset of .NET Framework—so, you may want to know what changes you need in your source code to adapt to the new framework. The other point you should be aware of is the third-party dependencies that need to be either changed or, in the worst case, removed altogether when migrating to .NET Core.

The first thing you should do is create an empty ASP.NET Core Web application project with the same name as your legacy project. I would suggest that first you should create a lean project with the minimal code and functionality inside and then slowly move the code from the legacy application to the newer one.

Note: The projects that target .NET Core should have the version of .NET Core specified in the <TargetFramework> element in the .csproj file, as shown next.


You should also update the .NET Core version in the global.json file.

   "sdk": {
      "version": "2.0.0"

Likewise, the package references should be updated in the <ItemGroup> section of the .csproj file.

   <PackageReference Include="Microsoft.AspNetCore.All"
      Version="2.0.0" />

You can refer to this migration document for more details in this regard.

Using the .NET Portability Analyzer

The best strategy to understand how to migrate is to analyze the portability requirements. Here is where the .NET Portability Analyzer comes to the rescue. This is a great tool that you should take advantage of to analyze how portable your application is for .NET Core and ASP.NET Core.

There are three variations of the .NET Portability Analyzer. These include the following:

  • Console Application
  • Visual Studio Extension
  • .NET Core Application

We will be exploring the Visual Studio Extension variation in this article. To get started using the .NET Portability Analyzer in Visual Studio, follow these steps.

  1. From within the Visual Studio IDE, click Tools -> Extensions and Updates.
  2. Next, select .NET Portability Analyzer and specify the target platforms—versions of .NET Core and ASP.NET Core you want to migrate your existing application to.
  3. Now, create a new ASP.NET project that targets .NET Framework 4.6.
  4. Name and save the project.
  5. Select the project and click “Analyze Assembly Portability” in the context menu.

Once the analysis is complete, you can view the report from the Portability Analysis Results window. Note that the results are displayed in three sheets—these include the following.

  • Portability Summary: This displays an executive summary report that depicts how portable the project is to the platform that has been targeted.
  • Details: This tab provides more granular details to help you understand what is incompatible.
  • Missing Assemblies: This tab provides you an insight on the assemblies that have been excluded from the analysis. A common reason to see an assembly listed here is when you are referencing an assembly that is present in the Global Assembly Cache (GAC).

You can learn more on the best strategies for migration to ASP.NET Core from this article.


This article presented an overview of the strategies, best practices, and tools that can be adopted to migrate legacy ASP.NET applications to ASP.NET Core. Happy reading!

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories