.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.
Table of Contents
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:
- Knowledge of C# and .NET Framework development.
- Familiarity with Visual Studio IDE.
- Understanding of .NET Standard 2.0 compatibility.
- Ability to install .NET Core on developer machines.
- 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:
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.
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.