.NET 5 Migration: Real World Lessons

Migrating a large enterprise monolith to .NET 5 is different from upgrading a “Hello World” app. We share lessons learned from migrating 50+ microservices, including handling breaking changes in ASP.NET Core and Entity Framework.

Breaking Change: JSON Serialization

System.Text.Json is the default now. If you rely heavily on Newtonsoft.Json quirks, switching is painful.

// Startup.cs - The compatibility fix
services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    });

Target Framework Monikers (TFM)

Stop using netstandard2.0 for application libraries (unless sharing with .NET Framework). Use net5.0 to unlock performance APIs like Span<T>.

Key Takeaways

• Use the **.NET Upgrade Assistant** tool.
• Audit 3rd party NuGet packages for proper .NET 5 support.
• Watch out for “split-packages” (e.g., `Microsoft.AspNetCore.App` vs `Microsoft.NETCore.App`).