Migrating from ASP.NET to ASP.NET Core with Project Migrations Part 5

Sayed Ibrahim Hashimi

Mike Rousos

December 8th, 20226 5

ASP.NET Core is a unified and modern web framework for .NET. Migrating existing ASP.NET apps to ASP.NET Core has many advantages, including better performance, cross-platform support (Windows, macOS, Linux), and access to all the latest improvements to the modern .NET web platform. But migrating from ASP.NET to ASP.NET Core can be very challenging and time consuming due to the many differences between the two frameworks. That’s why we’ve been working to provide libraries and tooling for performing incremental migrations from ASP.NET to ASP.NET Core so that you can slowly migrate existing ASP.NET apps a piece at a time while still enabling ongoing app development. In this blog series, we’ve been working on tooling in Visual Studio to simplify the migration experience, and a new update to the incremental ASP.NET migration tooling is now available. Along with this latest release of the incremental ASP.NET migration tooling extension, we’re happy to announce that the System.Web adapters libraries for ASP.NET Core have reached 1.0.

The incremental ASP.NET migration tooling extension can be installed from the Visual Studio Marketplace

The System.Web adapters ship in four packages:

In this series we’ve previously posted the following posts related to project migrations:

In this blog post we’ll cover the significant updates to the Project Migrations extension and System.Web adapters. We made the following improvements to the experience in Visual Studio when using the Project Migrations extension.

  • Endpoints explorer to visually represent which routes have been migrated
  • Added support for attribute based MVC controllers
  • Improved support for convention based MVC controllers
  • Support for API controllers
  • Support for Areas
  • Quality improvements in existing features

We will go into details for some of these areas now. Before we go through the updates, let’s summarize how you can get started with migrating an ASP.NET Framework project to ASP.NET Core.

Getting started

To migrate an existing ASP.NET Framework project to ASP.NET Core, first right click on the project in the Solution Explorer and select Migrate project. See the next image.

Migrate project context menu

After clicking on this menu option, the Project Migrations page will be opened.

Migrate project page

From here click on Start migration to enter the flow to migrate your project. After this you’ll be prompted to create a new ASP.NET Core project, or select an existing ASP.NET Core to use as the migration target project. After you go through the wizard you should end up back in the Project Migrations page with content that is like the following.

Migrate project with a partially migrated project

From here, you’ll use Migrate Controller, Migrate class and Migrate view to migrate your files to the new ASP.NET Core project. For more details see this previous blog post Migrating from ASP.NET to ASP.NET Core in Visual Studio. Now that we have recapped how to get started, let’s move on to discuss the updates. Let’s start with the Endpoints Explorer.

Endpoints Explorer

In this release we’ve added the ability to view which endpoints, or routes, have been migrated and those that remain to be migrated. For projects which have already started the migration process, when you go to the Project Migrations page you should now see something like the following.

Endpoints explorer button

This page now has a new button Endpoints explorer that will visualize the endpoints, or routes, which have been migrated and those which have not. When you click on that button, the Endpoints explorer view will be opened. See the following image.

Endpoints explorer in Migrate Project page

In this view the endpoints for the original ASP.NET Framework project are shown on the left side and the routes which have been migrated to the ASP.NET Core project are on the right. From this view, you can see that I’ve only migrated a small number of routes and that there is still a lot of work remaining before I complete this migration process. You can right click a route in this view and select Open in editor to view the source for that route. We hope that this can help you understand which routes have been migrated, and which remain to be migrated. Let’s briefly cover the other updates included in this release.

Other updates

In this release we’ve added support for migrating API Controllers. In previous releases we didn’t have first-class support for API Controllers. You could migrate API Controllers, but they would be migrated as a standard class instead of an API Controller. When migrating an API Controller, we now apply code transformations to improve the migration result.

We’ve also added support for Areas. In previous releases we didn’t have any knowledge of ASP.NET Areas during the migration process. Now when you migrate content in an ASP.NET Area, an Area will be created in the migration target project if needed. This should reduce the amount of work that you need to perform when migrating content in an ASP.NET Area.

In addition to these features we’ve improved the quality of existing features and added more transformers to reduce the amount of code that you need to manually fix up after the migration process.

System.Web adapter improvements

The System.Web adapter packages enable migrating projects with System.Web dependencies to .NET Standard, .NET 6, or .NET 7 by exposing common System.Web APIs via .NET Standard-compatible adapters. This enables migrating class libraries with System.Web dependencies to .NET Standard so that they can be used by both ASP.NET and ASP.NET Core callers in incremental migration scenarios. Available APIs include many commonly used members from HttpRequest, HttpResponse, HttpContext, and other common types.

In addition to the System.Web APIs, the System.Web adapters include new functionality to enhance incremental migration. While incrementally migrating a solution, portions of the web app will be served by the original ASP.NET project and portions will be served by a new ASP.NET Core project. For simple endpoints, this works well. But when the user’s session includes state – whether that’s session items or authentication decisions – it’s necessary to share this state between the two apps so that signing into one of the apps also signs into the other and so that a session item written by an endpoint from one app can be read by the other app. The System.Web adapters include functionality to enable sharing such state via connections between the ASP.NET Core and the ASP.NET apps.

The latest release of the adapters, version 1.0, is a stabilization release that fixes a number of bugs found in the original release candidate.

Documentation update

Documentation for both the System.Web adapters and the incremental ASP.NET migration tooling has been improved and added to learn.microsoft.com at https://learn.microsoft.com/aspnet/core/migration/inc/overview.

The documentation covers:

Give feedback

We want to hear from you how we can best improve the incremental ASP.NET migration experience. The best place to share your feedback with us is on GitHub in the dotnet/systemweb-adapters repo. Use the 👍 reaction to indicate features or improvements that are most important to you.

For more details you can check out the additional related resources listed below. Please try it out on your existing ASP.NET projects and share feedback so that we can continue to improve the incremental ASP.NET migration experience.

Thanks, and happy coding!

Resources

Sayed Ibrahim Hashimi Principal Product Manager, Visual Studio

Mike Rousos Principal Software Engineer, .NET Customer Engagement

Read next

6 comments

Discussion is closed. Login to edit/delete existing comments.

  • John King 0

    I’m still asking the Fastest and simplest solution : Copy and Past all Content/folder into new project and change namespace with option to
    – copy all content include view + html css js image to AppRoot ( /)
    – copy all static content into WebRoot (/wwwroot)

    • Sayed Ibrahim HashimiMicrosoft employee 0

      Hi John, thanks for your comment. We are working on adding support for migrating content files into the aspnet core project. I’m hoping that we will have that in the next release, but it’s still too early to commit to that.

      • John King 0

        nice to hear that, but please note that the point is about “ALL” not just the content . 1 by 1 migration is painfull if you can not remember which controller is been migrated and which one is not

  • prasad kulkarni 0

    Thanks for the great article.
    What about the migration of DLL’s that i refereed in ASP.NET application ?
    Please suggest

    • Taylor SouthwickMicrosoft employee 0

      Hi Prasad – that’s where Upgrade Assistant comes in. It will help you get your libraries targeting .NET Standard so that you can reference it from both applications.

      If you’re referring to 3rd party DLLs (i.e. ones that you don’t have the source to or own), then you’ll need to update to a version that supports .NET Core for best compatibility. There is a way to run those dlls as-is on .NET Core, but if an API has been removed or changed, you may get runtime exceptions so you’ll want to test any code you’re using there. Ideally, you want to get a supported version that targets .NET Standard or .NET Core there.

      If you are using System.Web.HttpContext in those libraries, that’s where the System.Web adapters mentioned above would be used.

      See https://dotnet.microsoft.com/en-us/platform/upgrade-assistant for getting started with the Upgrade Assistant.

  • 安银 卢 0

    Net Core 不支持静态文件SSI(Server Side Include)指令吗？像现在我们前端开发用vue，就需要大量的使用到include包含来进行开发

    Does net core not support static file SSI (server side include) directives? Like now we use vue for front-end development, we need to use a lot of include inclusion for development

Feedback usabilla icon