Migrating From .NET 4.8 to .NET 8

Upgrade Process

Basic upgrade process for projects

For C# projects (CSPROJ)

1. Convert C# projects to the new SDK-style format: https://learn.microsoft.com/en-us/dotnet/core/project-sdk/overview
   1. The .NET Upgrade Assistant can help with the project migration: https://learn.microsoft.com/en-us/dotnet/core/porting/upgrade-assistant-overview
   2. Convert packages.json into PackageReferences in your CSPROJ. https://learn.microsoft.com/en-us/nuget/consume-packages/migrate-packages-config-to-package-reference
2. Update the target framework for your projects from to net8.0-windows
   1. You can run the .NET Portability Analyzer on C# projects to evaluate how much work is required to make the migration.
   2. The .NET Upgrade Assistant can help with the .NET version migration: https://learn.microsoft.com/en-us/dotnet/core/porting/upgrade-assistant-overview
   3. If your application is a WPF application, then the CSPROJ will need net8.0-windows and true.
   4. If your application uses Windows forms, then use net8.0-windows and true.
3. System references can be removed from the CSPROJ, as they are available by default.
4. Then address incompatible packages, library references and obsolete (unsupported) code.

Global.json

You may need to set net8.0-windows as the target in your global.json, if you have one. Refer the link for global.json overview: https://learn.microsoft.com/en-us/dotnet/core/tools/global-json.

Component Versions

Common Issues

Here are some common issues you may encounter when upgrading to .NET 8:

Build Error CA1416

If your application uses functions that are only available on Windows systems, you may see a CA1416 error. This can be fixed for the project by adding [assembly: System.Runtime.Versioning.SupportedOSPlatformAttribute("windows")] to AssemblyInfo.cs.

Obsolete Classes and Functions with .NET 8

Your .NET 4.8 application may see compile time or runtime errors if it uses classes or functions that are obsolete or deprecated in .NET Core/5/6/7/8.

Assembly Loading

Your .NET 4.8 application may need updates to help it find and load assemblies:

• .NET 8 uses a different assembly probing approach for DLL loading. When in doubt, try putting the DLL to be loaded in the build output root directory.
• .NET 8 assembly loading details are different than .NET 4.8.
• .NET 8 projects need runtimeconfig.json files for many DLLs. The runtimeconfig.json needs to be installed next to the matching DLL, and it configures the behavior of that DLL. These files can be created with true.
• .NET 8 projects will create deps.json files for many DLLs. These deps.json files can be deleted if dependencies are placed in the same directory as the application. These files can be deleted with false.

Assembly Properties

After updating your application to .NET 8, you may see build errors for your assembly properties. Many assembly properties are now auto-generated and can be removed from AssemblyInfo.cs.

Double Numbers To String

If you have unit tests or integration tests that compare doubles as strings, they may fail when you upgrade to .NET 8. This is because the number of decimal places printed by ToString() for doubles is different in .NET 4.8 and .NET 8. You can call ToString("G15") when converting doubles to strings to use the old .NET 4.8 formatting.

String.Compare

String.Compare behavior has changed, see .NET globalization and ICU and Use Globalization and ICU.

Windows Dialogs May Change Appearance

Your dialogs may change appearance with .NET 8.

• WinForms dialogs experience UI layout changes. The workaround is to set Scale(new SizeF(1.0F, 1.0F)); in the dialog constructor.
• The dialog default font changed from "Microsoft Sans Serif 8 pt" to "Segoe UI". This can change dialog appearance and spacing.

Process.Start() May Fail

If your application is having trouble starting new processes, this may be because System.Diagnostics.Process.Start(url) has a behavior change. The ProcessStartInfo.UseShellExecute Property defaults to true in .NET 4.8 and false in .NET 8. Set UseShellExecute=true to workaround this change.

Encoding.Default Behaves Differently in .NET 8

If your application is having problems getting the text encoding used by Windows, it may be because Encoding.Default behaves differently in .NET 8. In .NET 4.8 Encoding.Default would get the system's active code page, but in .NET Core/5/6/7/8 Encoding.Default is always UTF8.

Items Order Differently in Sorted Lists

If you see different orderings of items in sorted lists after updating to .NET 8, this may be because List.Sort() behaves differently in .NET 8 than .NET 4.8. The change fixes a .NET 4.8 bug which affected Sort() of items of equal value.

System.ServiceModel

System.ServiceModel has been ported to .NET Core through CoreWCF, which is now available through Nuget packages. There are various changes, including <System.ServiceModel> not being supported in configuration files.

C# Language Updates

If you are building code from .NET 4.8 in .NET 8, you may see build errors or warnings about C# nullable types.

C# has introduced nullable value types and nullable reference types. Prior to .NET 6, new projects used the default disable. Beginning with .NET 6, new projects include the enable element in the project file.

You can set disable if you want to revert to .NET 4.8 behavior.

Environment Variables

If you use managed .NET to run native C++ code, be aware that environmental variables, including the path variable for DLL loading, are not shared from managed .NET code with native C++ code.