.NET 5 is Here: The Complete Migration Guide

.NET 5 is the first step in the “One .NET” vision, unifying .NET Core and Mono. It drops the “Core” branding but keeps the Core architecture. This guide covers the migration from .NET Core 3.1, highlighting the breaking changes and performance wins.

Project File Changes

Update your TFM (Target Framework Moniker).

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
    <!-- Optional: Enable C# 9.0 explicitly (default in net5.0) -->
    <LangVersion>latest</LangVersion>
  </PropertyGroup>
</Project>

Single File Applications

.NET 5 improves single-file publishing. It bundles all DLLs into one executable, though native dependencies still sit outside.

dotnet publish -r linux-x64 -p:PublishSingleFile=true --self-contained true

Performance Wins

• **GC Improvements**: Better scaling on high core-count machines.
• **PGO**: Profile Guided Optimization is now more accessible.
• **ARM64 Support**: Native performance on Surface Pro X and AWS Graviton2.