How to Convert .NET Framework to .NET Core: Migration Guide

.NET Core is the future of .NET development. 307,964 live websites are now active using .NET Core. It is free, can be used on any operating system, and has many performance enhancements over the .NET Framework.

As companies look to modernize their legacy .NET Framework apps, converting them to .NET Core has clear benefits. However, migration requires some planning and effort. This guide will walk you through the key steps to convert a .NET Framework application to .NET Core.

Overview of .NET Core

.NET Core, first released in 2016, is an exciting new chapter for .NET development. This open-source, cross-platform implementation offers many benefits over the original .NET Framework.

For starters, the entire platform is open-source now, allowing for more community engagement and contribution. This kind of transparency and collaboration is always welcome!

Also, .NET Core applications can run on Windows, MacOS, and Linux machines out of the box. By contrast, the .NET Framework locked us into the Windows ecosystem. The flexibility to deploy .NET apps anywhere opens up a world of new possibilities.

Extensive rearchitecting work under the hood has also improved performance in .NET Core. Tests show gains across the board for real-world apps—we’ll take those speed boosts, thank you very much!

Another neat feature is the ability to have multiple versions of .NET Core installed side-by-side without conflicts. This makes things much simpler when dealing with complex migration scenarios across environments.

There are also all-new APIs tailored to modern application development techniques and distributed systems. Innovation continues as the platform matures.

When it’s time to replace aging systems, .NET Core should absolutely be considered the future vision for .NET development. 

Prerequisites

Before beginning your migration NET framework to NET Core, make sure your development environment meets the following prerequisites:

  1. Knowledge of C# and .NET Framework development.
  2. Familiarity with Visual Studio IDE.
  3. Understanding of .NET Standard 2.0 compatibility.
  4. Ability to install .NET Core on developer machines.
  5. Access to existing .NET Framework application source code.

Also, ensure that third-party libraries used in the application are compatible with the .NET Standard 2. 0. This will ensure that those dependencies can be reused in the .NET Core.

Migration Process Overview

At a high level, here are the main steps to migrate a .NET Framework app to .NET Core:

See also  CPANEL/WHM: How to configure a domain to use Sendgrid SMTP

1. Identify Breaking Changes

The first one is to determine if any breaking changes in .NET Core can potentially affect your application code. Some examples include: 

App Domains 

App domains are no longer supported in .NET Core. Applications that depend on API calls of AppDomain will have to undergo some changes. 

Reflection 

In most reflections, APIs have been changed or removed in .NET Core. Use the audit and test in proportion to the results of the audit. 

Serialization 

Problems associated with binary serialization can be encountered in .NET Core. If possible, use JSON serialization. 

Globalization 

Check code that deals with culture, encoding, and globalization. These areas have breaking changes. 

File System Access 

The APIs of the file systems have been changed to the asynchronous models. Audit file system interactions. 

Enumerate all the areas of breaking change risk before making massive changes in the code. This will help minimize such problems during migration so that they do not arise in the later stages.

2. Port Application Code

Once you have addressed breaking changes, the next step is to port your feature code to target .NET Core.

Create .NET Core Project

Add a .NET Core project to your solution. Move feature code classes and assemblies over from old projects. Link relevant project references.

Update Namespaces

.NET Framework namespaces are different from .NET Core namespaces in some cases. Update these as needed.

Replace Legacy APIs

Swap out deprecated APIs and frameworks for new .NET Core alternatives. Examples include Entity Framework 6 to Entity Framework Core.

Enable Tiered Compilation

Improve debug performance by enabling tiered compilation in Visual Studio. This allows incremental edits without full recompilation.

Handle Project Compatibility

Use the dotnet CLI to test whether projects build correctly. The dotnet migrate command can automatically handle certain compatibility issues.

During this phase, focus on moving application logic to .NET Core. Expect some functionality to remain broken until later phases.

3. Migrate Third-Party Dependencies

With core logic migrated the next focus is getting third-party libraries compatible. NuGet is the primary mechanism for .NET library distribution.

Check NuGet Packages

Use the NuGet package manager to view all referenced packages in your solutions. Record current versions in use.

Identify Compatible Versions

Search online to identify which package versions support .NET Standard 2.0 for cross-compatibility.

See also  Integrating SonarQube with Jenkins: Automate Code Quality Checks

Install Updated Packages

Use NuGet package manager to update packages to their .NET Core compatible versions. Resolve any new dependency issues.

Replace Incompatible Packages

Some third-party libraries may not fully support .NET Core. In these cases, find alternate libraries that provide the same functionality.

Audit Breaking Changes

Updated library versions may contain subtle changes that are different from what your application code expects. Test thoroughly after upgrading.

Invest time upfront to validate third-party libraries. It prevents ending up with incompatible dependencies down the road.

4. Set Target Frameworks

At this point, all application codes should be built successfully on .NET Core. The next step is configuring separate target frameworks for test projects versus production code.

Update Unit Test Projects

For test projects, set the target framework to netcoreapp3.1 to test against the .NET Core 3.1 LTS release.

Set Production Target

For release configuration, set the target framework to net5.0 to use the latest .NET 5 runtime release.

Allow Framework Version Portability

Add the <TargetFrameworks> node to allow the same projects to compile for both environments and provide version portability.

Configure Conditional Compilation

Use conditional compilation symbols like NETCOREAPP to isolate code specific to .NET Core where required by libraries.

Separating target frameworks improves developer productivity. Tests can run against LTS runtime while production uses the latest version.

5. Run Validation Testing

The final step is to perform a thorough check on all the application functionalities after all the codes and configurations have been moved to the new environment. 

Functional Testing 

Run integration tests on all the major use cases to ensure that business logic behavior is correct. 

Performance Testing 

Profiling and load testing of the application performance can be done using a suite like Visual Studio Diagnostics Tools. 

Security Scanning 

It is possible to scan applications for security flaws either manually or using an SAST tool. OWASP ZAP is an open-source option. 

Platform Validation 

If testing for multiple runtimes, then test the application on all the supported platforms like Windows and Linux. 

Schedule time to address problems that may be identified during the testing phase. When sign-off criteria have been reached in testing areas, prepare for the production release.

Summary

Migrating a legacy .NET Framework application to .NET Core is a little more complex and demands preparation and work, but the payoff is well worth it in the long run. Follow this guide’s step-by-step process.

Pay much attention to quality and testing at each phase of the migration. The result will be a contemporary. NET Core application, which can fully benefit from new platform advancements.

Leave a Comment