Upgrade Web App from .Net 5.0 (3.1) to 8.0 --- Manually

Note: This article is published on 09/30/2024.

These two articles are to upgrade .Net Core Web App from lower version (5.0 and 3.1) to 8.0. There are two ways to go, one is manually, another one following MS Upgrade Assistant.

Upgrade Web App from .Net 5.0 (3.1) to 8.0 --- Manually --- this article
Upgrade Web App from .Net 5.0 (3.1) to 8.0 --- by MS Upgrade Assistant

A - Introduction

Software updating is necessary. For .Net:

This article will discuss the Upgrading from .Net 5.0, 7.0 or 3.1 to .Net 8.0. The way is called Manually, because we follow the instruction from Microsoft to make the updating in a general way, without using any upgrading tool to do the task. It is quite successful.

The content of the article includes:

A - Introduction
B - The Way to follow
C - Update Process
- C.1 - Prerequisites
- C.2 - Upgrade the .Net Version in Visual Studio
- C.3 - Update package References
D - Error Handling
E - New Hosting Model

B - The Way to follow

We follow the Microsoft upgrade instructions:

Microsoft .Net Core Version Update

Usually two steps

Update the TargetFramework --- version updating, such as

Update the Package References, such as

Those happened in the version updating:

6 to 7
7 to 8
8 to 9

Version updating for 5 to 6, one more possible step is

The minimal hosting model:

Significantly reduces the number of files and lines of code required to create an app. Only one file is needed with four lines of code.
Unifies Startup.cs and Program.cs into a single Program.cs file.
Uses top-level statements to minimize the code required for an app.
Uses global using directives to eliminate or minimize the number of using statement lines required.

C - Update Process

The updating steps:

C.1 - Prerequisites

As Microsoft suggested:

Visual Studio 2022 with the ASP.NET and web development workload.

In fact, if you click the Individual components button, you will see the current version of .Net will be chosen for installation, but other versions might not. However, you can choose whatever you want or like, they are installed side by side, there is no hurt except the disk.

On the other hand, if you only choose the current version, when you open some apps in old version, Visual Studio will auto warn you to re-install. That is just one click.

C.2 - Upgrade the .Net Version in Visual Studio

This is quite straight forward:

Open the .Net App with Visual Studio 2022
Right Click the Project => Properties to open the properties window:

In the default page, Application, you will see the Target framework, here is .Net 5.0

Use the dropdown box to show the versions available, and choose what you want, compile. Done.

The result will be something like this:

C.3 - Update package References

We do not follow Microsoft, still use the IDE (Integrated Development Environment), Visual Studio.

Open the app in Visual Studio 2022
Open Manage NuGet Packges by
- Click Tools =>
- NuGet Package Manager =>
- Manage NuGet Packages for Solution
- to open the tab: NuGet - Solution
In the NuGet Window:
- Click Updates on the top: here there are 30 items needed to update
- Choose Select all packages on the left pane
- Click Update button on the right pane

After Click the Update Botton --- run, the result will be like this

In this way, we will update the all packages whatever from Microsoft or not, while the sugestions from Microsoft and the Upgrade Assistant only update the Microsoft stuff. Those have two bad effects:

It will not update all you need to updating;
Most likely, you might meet some compatible issue with Microsoft pachages updated while others not.

When we do this in Visual Studio, updating the whole packages, if good, one click we can complete our task. Otherwise, the all error created will be the real errors we have to handle. While if we update partially, it could create some uncompatible issue betweeen the version we updated and the version not. I will discribe some example from another article:

Upgrade .Net Core Web App from .Net 5.0 (3.1) to 8.0 --- by MS Upgrade Assistant

D - Error Handling

After updating, there will be a lot of errors, however, only several major ones are resolved, others will be disppeared. Here we will list several typical errors.

Error 1: ambiguous

This is an auto mapper's error.

Code

CS0121

Description

The call is ambiguous between the following methods or properties:
'Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddAutoMapper(Microsoft.Extensions.DependencyInjection.IServiceCollection, params System.Type[])' and 'Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddAutoMapper(Microsoft.Extensions.DependencyInjection.IServiceCollection, params System.Type[])'

The ambiguous is due to when you added the auto mapper v.13, the v.12 is still existing. Delete it, the error gone. This is a typical error, could happen in different modules.

Error 2: Reference missing, just get it back from NuGet. There are a bunch of these kind of errors.

Error 3: Cannot implicity convert type --- this was good in previous version, but no good in new version

Fix:

Error4: this error is caused by MS DocumentFormat.OpenXml version 2.20 above. Dut to the fix needs to change code, we just update to v 2.20 and leave it update to the latest version for developer to handle.

E - New Hosting Model --- Minimal Hosting Modle

Since .Net 6, .Net Web App uses the New Hosting Model called Minimal Hosting Modle that combines two files, program.cs and startup.cs in the previous versions, into one file, program.cs, for the starting up process.

This model makes the starting up process code simpler and clear. Especially, .NET 6 introduces implicit namespace support for C# projects. To reduce the amount of using directives boilerplate in .NET C# project templates, namespaces are implicitly included by utilizing the global using feature introduced in C# 10.

However, . Apps migrating to 6.0 don't need to use the new minimal hosting model, see more info Apps migrating to 6.0 don't need to use the new minimal hosting model. At this point, some, or most people will choose not updating the old hosting model to the new minimal hosting model. Migrating to the new minimal hosting modle, there are two benefits:

Changing the code style to reduce two page file to one,
Introducing ImplicitUsing support to reduce the amount of using directives in the code everywhere.

For a complex app, to merge the startup.cs to program.cs might include a lot of code changes associated with testing process, it might not to do so; on the other hand, the using directives have been used in the app anywhere, getting rid of them besides not time consuming but also not necessary.

At this point, we skip the upgrading from the old .Net 3.1 and 5.0 Hosting Model to the new minimal hosting model, but updating the reference for the ImplicitUsing directive support, which will the later coding without needs to use some included using directives.

The ImplicitUsing support is added by the following:

References:

2 Comments

Join the conversation! Your thoughts help the community grow.

Tuhin Paul1y ago
Thank you for sharing this detailed guide . You mentioned that migrating to the new minimal hosting model is optional, and some developers might choose not to update the old hosting model. Are there any specific scenarios or project requirements where it's recommended to stick with the old hosting model, or is it generally recommended to migrate to the new minimal hosting model for new projects or when upgrading to .Net 8.0?
- George1y ago
  Thanks for visiting. It is just not necessary if not required. It is a lot of work to do it, and also test it. Regression testing, not just one person work, but team work. But without a lot benefits. Especially for a done project. If the project is new, it might be worthful to do so. Microsoft does not recommed to do so.