DEV Community

Adrián Bailador
Adrián Bailador

Posted on

Migrate a project to .NET 8

#dotnet #webdev #programming #csharp

Migrating a .NET Core 3.1 project to .NET 8 might seem challenging, but the process becomes much smoother with the right guide. Here’s a step-by-step guide:

Why Upgrade to .NET 8?

Before starting, let’s ask ourselves: why migrate to .NET 8? Here are some key reasons:

  • Better performance: more optimization and lower memory consumption.
  • Long-Term Support (LTS): .NET 8 will be supported until at least 2026.
  • Improved JSON Serialization with System.Text.Json.
  • New features in minimal APIs and Blazor, making web development easier.
  • Enhanced security in authentication and authorization.

1. Review Your Dependencies

Before migrating, it’s essential to check whether your dependencies and external libraries are compatible with .NET 8.

  1. Check your current project version using: 
   dotnet --version
Enter fullscreen mode Exit fullscreen mode

If you see something like 3.1.x, you're still on .NET Core 3.1.

  1. Analyze your dependencies:

    • Open the .csproj file and review the NuGet packages you're using.
    • Use this command to check which packages need updating: 
     dotnet list package --outdated

  2. Tools that can help:

    • Use dotnet upgrade-assistant to simplify the migration: 
     dotnet tool install -g upgrade-assistant
 upgrade-assistant upgrade <projectPatch>

This will provide a list of suggested changes and help automate parts of the upgrade process.

  1. Check the official documentation for each package to confirm compatibility with .NET 8.

2. Update the SDK to .NET 8

  1. Download and install the .NET 8 SDK from the official Microsoft page:

    Download .NET 8

  2. Verify the installation:

   dotnet --version
Enter fullscreen mode Exit fullscreen mode

If everything is fine, you should see something like 8.X.X.

3. Update the .csproj File

Open the .csproj file and change the Target Framework version:

Before (in .NET Core 3.1):

<TargetFramework>netcoreapp3.1</TargetFramework>
Enter fullscreen mode Exit fullscreen mode

After (in .NET 8):

<TargetFramework>net8.0</TargetFramework>
Enter fullscreen mode Exit fullscreen mode

If you have multiple projects, repeat this step for each one.

4. Update NuGet Dependencies

Run the following commands to clear the cache and update packages:

   dotnet nuget locals all --clear
   dotnet restore
Enter fullscreen mode Exit fullscreen mode

To update all dependencies to the latest compatible version:

   dotnet outdated --upgrade
Enter fullscreen mode Exit fullscreen mode

(If you don’t have dotnet outdated, install it using dotnet tool install --global dotnet-outdated-tool)

5. Code Adjustments

.NET 8 introduces several important changes. Here are some of the most relevant ones:

5.1. Changes in Startup.cs and Program.cs

In .NET Core 3.1, Startup.cs handled configuration. Now, in .NET 8, everything moves to Program.cs.

Before (3.1 with Startup.cs)

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}
Enter fullscreen mode Exit fullscreen mode

After (8.0 with Program.cs)

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.UseAuthorization();
app.MapControllers();
app.Run();
Enter fullscreen mode Exit fullscreen mode

5.4. Changes in Authentication and Authorization

If your project uses authentication with JWT or IdentityServer4, you may need some adjustments:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://your-authentication-server";
        options.Audience = "api";
    });
Enter fullscreen mode Exit fullscreen mode

5.5. JSON Serialization Optimization

If you previously used Newtonsoft.Json, you can now take advantage of System.Text.Json with optimized configuration:

builder.Services.Configure<JsonOptions>(options =>
{
    options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    options.SerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
});
Enter fullscreen mode Exit fullscreen mode

6. Test Your Application

  1. Build and run the application: 
   dotnet build
   dotnet run
Enter fullscreen mode Exit fullscreen mode
  1. Check for any errors or warnings.
  2. Run unit tests: 
   dotnet test
Enter fullscreen mode Exit fullscreen mode

7. Final Steps Before Deployment

If you use Docker or Azure, check the following:

  • If using Docker, update the base image in Dockerfile: 
  FROM mcr.microsoft.com/dotnet/aspnet:8.0
Enter fullscreen mode Exit fullscreen mode
  • On Azure App Services, verify that the Azure runtime supports .NET 8.

Top comments (0)