?? Migrating a .NET Framework 4.7 Application to .NET Core: Key Insights and Tips for a Successful Transition

Migrating legacy .NET Framework applications to .NET Core/8 can unlock a world of improvements—performance boosts, cross-platform compatibility, and modern libraries. However, the journey requires thoughtful planning and strategy. Recently, we completed a migration of a complex .NET Framework 4.7 solution to .NET Core, and I wanted to share some key insights, challenges, and best practices we found useful along the way.

1?? Choosing the Right Migration Path

Every project has unique complexities, so there’s no “one-size-fits-all” for .NET migrations. For this project, we balanced incremental migration with some ground-up rewrites, leveraging both manual refactoring and Microsoft’s migration tools. Starting with backend services and low-dependency modules worked well, as it allowed us to test core functionality in isolation before tackling UI-heavy components. This approach minimized disruption and gave us flexibility to validate each segment of code as we progressed.

2?? Resolving UI and API Compatibility Issues

When the backend was stable, we faced the challenge of synchronizing our UI request and response payloads with new backend requirements. Here’s how we tackled some of the key issues:

Setting JSON Serialization to Pascal Case

We needed the API to return responses in PascalCase, matching the client’s expectations:

// In Program.cs or Startup.cs (for .NET Core 3.1+)
services.AddControllers()
    .AddJsonOptions(options => {
        options.JsonSerializerOptions.PropertyNamingPolicy = null; // PascalCase by default
    });        

Using Refit for Simplified API Calls

Refit streamlined our API client setup, allowing us to define interfaces for endpoints without manually handling HTTP requests:

// Define the interface for an API endpoint
public interface IComplianceApi
{
    [Get("/api/compliance/{id}")]
    Task<ComplianceRecord> GetComplianceRecordAsync(int id);
}
// Use dependency injection to set up the Refit client
services.AddRefitClient<IComplianceApi>()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.yourservice.com"));        

In the controller or service, we simply inject IComplianceApi and call methods directly, keeping the code clean and reducing error handling.

Handling Serialization Differences with Custom Middleware

For backward compatibility, we used a middleware to ensure payloads met both old and new formats:

// Middleware to force type conversions and handle missing properties
public class RequestTransformationMiddleware
{
    private readonly RequestDelegate _next;
    public RequestTransformationMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        context.Request.EnableBuffering();
        using var reader = new StreamReader(context.Request.Body, leaveOpen: true);
        var body = await reader.ReadToEndAsync();
        var transformedBody = TransformPayload(body);
        context.Request.Body = new MemoryStream(Encoding.UTF8.GetBytes(transformedBody));
        await _next(context);
    }
    private string TransformPayload(string body)
    {
        // Logic to adjust properties or types in payload
        return body.Replace("oldProperty", "newProperty");
    }
}
// In Startup.cs
app.UseMiddleware<RequestTransformationMiddleware>();        

3?? Merging and Managing Parallel Versions

One of our biggest challenges came from managing two project versions: the original .NET Framework solution and the new .NET Core project. To minimize conflicts, we initially worked with duplicate projects and libraries, but ultimately streamlined the codebase by removing outdated dependencies and renaming projects to match legacy naming. This was crucial to maintain version control stability.

4?? Infrastructure and Deployment Considerations

Deploying to IIS required additional setup and permissions. Here are a few server-side lessons:

- Ensure .NET 8 SDK and ASP.NET Core Hosting Bundle are correctly installed.

- Adjust folder permissions for the API’s application pool user, as permission issues often prevent apps from starting.

- Missing IIS modules were resolved by installing the Windows Hosting Bundle—essential for any environment replicating the on-premises setup.

5?? Leveraging Testing and Intelligent Tools (IA)

Visible issues often surface with compiler warnings, but hidden issues typically emerge during UI testing. Using intelligent automation (IA) tools to establish a suite of UI and functional tests can catch edge cases that manual methods or tools like Postman might miss. Automated tests across different environments and scenarios ensure that UI flows remain smooth and functional under various conditions.

Using Feature Flags to Gradually Release Updates

Feature flags allowed us to safely test new backend responses before fully rolling them out. Here’s a simple example of a flag-based approach:

public class ComplianceService
{
    private readonly bool _useNewFeatureFlag;
    public ComplianceService(IConfiguration config)
    {
        _useNewFeatureFlag = config.GetValue<bool>("Features:UseNewCompliance");
    }
    public async Task<ComplianceRecord> GetComplianceRecordAsync(int id)
    {
        if (_useNewFeatureFlag)
        {
            // New approach logic
        }
        else
        {
            // Legacy logic
        }
    }
}        

?? Final Thoughts: Migrations are challenging, but they’re also an opportunity to refine architecture, improve code quality, and embrace modern tools. By approaching migration incrementally, using Refit and feature flags, and leveraging intelligent testing, we can transform our legacy systems without disrupting core business functionality.

If you're going through a similar process or have questions, let’s connect! ??