Accelerate .NET application modernization with Porting Assistant for .NET Visual Studio IDE extension

Many organizations have .NET Framework legacy applications they want to modernize to .NET Core or .NET 5 to take advantage of the performance, cost savings, and robust ecosystem of Linux. It’s why AWS launched Porting Assistant for .NET in July 2020. Porting Assistant helps developers accelerate the conversion of their code from the Windows-only .NET Framework runtime to the cross-platform .NET runtime.

Over the months since that initial release, AWS has released the tool as an open source project and has continued to add new features to improve the developer experience, such as the Code Translation Assistant feature announced in December 2020. Porting Assistant was initially released as a standalone desktop tool. That means, you would perform the analysis and conversion of your projects from within the Porting Assistant, and then you would switch to your IDE of choice to perform any remaining tasks necessary to complete the conversion of your .NET Framework projects to target .NET/.NET Core.

On May 4th, 2021, we announced that you are now able to run the Porting Assistant as an extension to the Visual Studio IDE, allowing you to perform all of the tasks necessary to convert your code without needing to switch between your IDE and the Porting Assistant tool. Through this integration with Visual Studio, developers can remain in their familiar development environment.

Another benefit of this integration is that developers no longer must refer to an assessment report to identify the sections of code that will require attention during the porting exercise. Instead, the extension uses Visual Studio’s standard Error List tool window to list these sections and provides developers with a way to navigate to that code by clicking the error item. The extension is also able to provide contextual guidance for a developer as they modify their code. It shows suggestions for changes where possible and provides the ability to make those changes on-demand using Visual Studio’s Code Actions feature. It is also possible to automate those changes during the process of porting the code to .NET.
In this post, I explain how to analyze and port .NET Framework applications to .NET Core or .NET 5 using Visual Studio Extension for Porting Assistant for .NET. For more information, you can visit user guide.

Getting Started

Installing the Porting Assistant extension follows the same process as most other Visual Studio extensions. You can find the extension in the Visual Studio Marketplace; it’s available free-of-charge and delivered as a standard VSIX package that Visual Studio will automatically install. In this initial release (v1.0.0 as of the time of this article), only Visual Studio 2019 is supported.

By default, the Porting Assistant extension will use the latest version of the .NET Core framework detected on your machine as the target runtime for the code conversion. If you have multiple versions installed and would like to change this default target, you can change this behavior under the Porting Assistant’s settings. This can be accessed through either the Porting Assistant’s Extensions submenu by selecting “Porting Assistant Settings…,” or via the Tools, Options submenu under the PortingAssistant Extension option.

Configuring the behavior of the Porting Assistant Extension.

In addition, the Porting Assistant extension sends anonymous usage data to AWS by default. You can view a description of the types of usage data AWS collects by navigating to the “Data usage sharing” option If you would like to change this behavior, you can clear the check box under the “Data usage sharing” option.

In this initial version of the extension, there is an incompatibility with IntelliCode’s C# recommendations and the Code Actions provided by the extension. For the extension’s Code Actions to function properly, you must disable IntelliCode C# suggestions under the Tools, Options, IntelliCode option.

Assessing Your Code for Porting

If you are familiar with the standalone Porting Assistant for .NET tool, the process of porting your code starts with an assessment of your solution. When using the extension, you begin an assessment by first opening a solution, then opening a C# file. After you have opened a C# file, you then select the “Run Full Assessment with Porting Assistant” menu item available as a context menu on the Solution node or under the main menu under the Analyze menu or the Extensions->Porting Assistant for .NET menu. Similar to the experience on the desktop version, this assessment runs in the background after you start the analysis. When the assessment has completed, you will see a notification in the IDE (see below).

The assessment completion notification

There are two major differences to the assessment user experience from within Visual Studio. Rather than opening an overall assessment for the solution, you can now view assessment results directly from within Visual Studio. After the assessment has completed, you can view a list of porting actions that the assessment identified in Visual Studio’s Error List window when you open your C# files. The recommendations are currently classified into two categories: PA0001 and PA0002. Items classified as PA0001 may require manual code changes whereas items classified as PA0002 indicate that they can be resolved using automated actions.

An example of Porting Assistant findings after an assessment.

If you navigate to the line indicated in the recommendation (or double-click on the recommendation), you will see that the code has been underlined with a green “squiggle,” indicating that there are actions that can be taken on the code.

An example of a line of code that can have actions performed on it before porting.

The other enhancement to the assessment process is that the extension is capable of continuously assessing your projects rather than having to manually start it as you would from within the desktop version. To use this feature, navigate to either the menu items described above or bring up the context menu for the solution, and ensure that the “Enable Incremental Assessments” menu item has been checked. When incremental assessments have been enabled, the Porting Assistant will automatically re-evaluate the code in a file after you save your changes and update the list of recommendations.

Porting Your Code

After you have loaded a .NET Framework solution and performed an assessment, you can start the porting process by opening the context menu for the solution in the Solution Explorer or by navigating to the “Port Solution to .NET Core” menu item under the Project menu. You can also choose to port individual projects by opening the context menu for the specific project or by navigating to the “Port Project to .NET Core” menu item under the Project menu.

Unlike the desktop version, the extension does not prompt you for whether you would like to convert your code in-place or to copy the ported code to a new location. Instead, the extension ports your code in-place overwriting your existing .csproj and .cs files with the converted projects and code. If you would like your original code to remain unmodified, then either ensure that the code is under version control or perform the porting process on a separate copy of the original code.

After you have started porting your code, the extension will present you with a message box. This message box will warn you of the fact that your code is being modified in-place and that these changes cannot be undone, and it also provides a check box that allows you to indicate whether any suggested code changes from the assessment should be applied automatically during the conversion process. If you select this check box, the Porting Assistant’s Code Translation Assistant feature handles many changes that a developer would otherwise must perform manually. The changes include simple things such as updating the using statements from .NET Framework-only namespaces to those supported by .NET Core, but can also be more complex, like renaming files that are no longer supported under .NET Core, such as Global.asax, and removing them from the project’s Compile ItemGroup.

The message box presented by the Porting Assistant before porting.

Once you are ready to start the porting process, you then press the “Port” button on the message box. The Porting Assistant will then start processing the Projects in your solution; it will automatically convert the projects from the old MSBuild-style format to the new SDK-style project format supported by .NET Core and, based upon whether you selected the check box for automatically applying changes, will automatically modify your code. Once the porting process has completed, you will be presented with a notification indicating this completion along with what version of the .NET Core runtime it ported the solution and projects to.

The message box presented by the Porting Assistant after the porting process completes.

After the porting process has completed, you are now able to view any remaining steps you should perform in order to complete the porting process. If you chose the option to allow the Porting Assistant extension automatically apply changes, all that remains is resolving any remaining build errors. However, if you chose to apply the changes yourself, you will see the green “squiggly” indicators showing where the Porting Assistant’s has recommendations or can perform changes for you using Code Actions. If you hover over the line, you will see a summary of the recommendation.

An example of a line of code that can have actions performed on it after porting.

When manually resolving these issues, the Porting Assistant extension integrates with Visual Studio’s Code Actions feature. With Code Actions, an indicator (a light bulb) will appear in the code’s margin when you either hover over a line of code with the green “squiggly” or place the insertion caret on the line. If you either click this lightbulb or use the CTRL-. Hotkey combination, a list of Code Action options will appear, including those provided by the Porting Assistant.

An example of a Code Action provided by the Porting Assistant.

Regardless of whether you elect to have the Porting Assistant automatically apply changes for you, to use Code Actions to make these changes, or to manually apply those changes yourself, you may find that there are still compilation errors to be resolved before all of your projects can successfully compile. If you have enabled incremental assessment, the Porting Assistant will continually update its list of detected issues as you make your changes, but you can also refer to the list of build errors that will result from your builds and resolve those until all projects compile without errors.

After you have completed the process of converting your code to .NET Core, there is one final, optional step you may want to take. While your code is actively being ported and you are resolving any remaining issues, the extension adds an ItemGroup to each .csproj file with a label of “PortingInfo” and the set of items in this ItemGroup are used by the analysis engine. Once you have fully completed the porting process, this ItemGroup may safely be removed from your project to reduce the overall size of the .csproj files. If for some reason you determine that you must resume porting your application, you can perform a full assessment of your solution and the ItemGroup will be re-created.

Conclusion

In this article, I walked through the capabilities of the Porting Assistant extension and how it extends the Visual Studio IDE to help developers streamline the process of porting .NET Framework code to .NET Core. Though using this extension does not eliminate the need for source code changes, it does accelerate the pace at which the .NET legacy applications can be transformed.

If you encounter any issues using the extension, you can request support by using the menu item under the Porting Assistant’s Extensions submenu. If you select the “Contact Support” menu item, a new email message will be created using your default email application, or you can directly email the team at aws-porting-assistant-support@amazon.com. If you have any feature requests, please send them to us via issues in the Git repository at https://github.com/aws/porting-assistant-dotnet-datastore. We also welcome contributions from the development community as GitHub Pull Requests.

You can download the Porting Assistant for .NET Visual Studio IDE extension from the Visual Studio Extensions Marketplace for free. We’d love to see what you build on AWS with it!

About the Author

Andy Hopper is a Principal Specialist Solutions Architect at AWS, and specializes in helping customers migrate and modernize Microsoft .NET and Windows workloads into their AWS environment.