Migrate a C# project from .NET Core 3.1 to .NET 8.0

In this article, I explain how to migrate a C# project from .NET Core 3.1 to .NET 8.0, including updating your SDK, project files, dependencies, and testing your application.

1. Install .NET SDK 8.0

Download and install the latest .NET 8.0 SDK from the official .NET download page.

Check your installed .NET SDK:

dotnet --list-sdks

You should see in the output:

8.0.411

Check your installed .NET Runtimes:

dotnet --list-runtimes

You should see in the output:

Microsoft.AspNetCore.App 8.0.17
Microsoft.NETCore.App 8.0.17
Microsoft.WindowsDesktop.App 8.0.17

2. Update Your Project File

Open your .csproj file and set the TargetFramework to net8.0:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  ...
</Project>

3. Update NuGet Packages

Update all NuGet dependencies to their latest versions, as older packages may not support .NET 8.0.

dotnet list package --outdated
dotnet add package  --version 

4. Review and Update Code for Breaking Changes

Check for breaking changes between .NET Core 3.1 and .NET 8.0. Review your code for obsolete APIs and update as needed. Refer to the official Microsoft breaking changes documentation for guidance.

5. Update global.json (if present)

If your repository uses a global.json file to pin the SDK version, update it to reference the new SDK:

{
  "sdk": {
    "version": "8.0.x"
  }
}

6. Test Your Application

Run all your tests and start your application to ensure everything works as expected after migration.

Migration Checklist

• Install .NET 8.0 SDK
• Check the installed .NET SDK
• Check the installed .NET Runtimes
• Update TargetFramework to net8.0 in .csproj
• Update all NuGet packages to compatible versions
• Review and resolve any breaking changes
• Update global.json if used
• Run and verify all tests and application functionality

By following these steps, you can successfully migrate your C# project from .NET Core 3.1 to .NET 8.0 with minimal issues and take advantage of the latest features and improvements in the .NET ecosystem.