In this article, we will learn how to switch between .NET SDK versions in our projects.

By default, .NET uses the latest SDK installed on a given machine, even when developing with an earlier .NET runtime version. Actually, we can benefit from the latest SDK features and improvements while we are still able to use an older .NET runtime due to downward compatibility. But in certain rare cases, we may want to set a specific .NET SDK version for a project.

To download the source code for this article, you can visit our GitHub repository.

With that, let’s dive in.

Support Code Maze on Patreon to get rid of ads and get the best discounts on our products!
Become a patron at Patreon!

Managing SDK Versions

To check the latest .NET version, we use the dotnet --version command. To check all available installed .NET SDK versions, we can use dotnet --list-sdks:

Microsoft Windows [Version 10.0.19045.3693]
(c) Microsoft Corporation. All rights reserved.

C:\Users\Username>dotnet --version
8.0.100

C:\Users\Username>dotnet --list-sdks
7.0.404 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

Every time we update Visual Studio and the .NET version changes, the Visual Studio installer also installs a newer .NET SDK version and replaces the older one. To utilize an older version explicitly, we often have to install it manually. The directory for our installed .NET SDKs is usually C:\Program Files\dotnet\sdk.

If you’d like to learn more about the .NET CLI and SDK, check out our previous articles.

Using global.json to Switch Between .NET SDK Versions

To set the .NET SDK version we need to add a global.json file to our project. The file can be created anywhere in the file hierarchy. The CLI searches from the directory upwards for a global.json file from the current directory. We recommend creating this file in the project root directory.

Let’s define a global.json file, setting the version to 8.0.0:

{
  "sdk": {
    "version": "8.0.0"
  }
}

Also, we can easily create a global.json by using the .NET CLI:

dotnet new globaljson --sdk-version 8.0.0

Here, we create a global.json file from a template with the specified version in the argument.

If the SDK specified in the global.json isn’t installed or found, the .NET CLI uses matching rules to select a compatible SDK. It attempts to use a similar version but fails if no such version is found. If there are multiple global.json files, .NET uses the first one found. If .NET does not find any global.json file, it uses the latest installed SDK.

Troubleshooting .NET SDK Versions

When we set the version in our global.json file, we prevent the user from building with a different SDK. If a user doesn’t have the specific version installed and tries to build the project in Visual Studio, the following error occurs: NETSDK1141 Unable to resolve the .NET SDK version as specified in the global.json located at Path_to_project. We expect this error, and in fact, it illustrates that our global.json is working properly. We can resolve it by installing the version specified in the file.

Additionally, we have to make sure that the target .NET runtime version is never higher than the .NET SDK version. And finally, we have to keep in mind that .NET searches for the global.json file upwards from the current directory.

Conclusion

The global.json file allows an explicit SDK version setting for a project, ensuring consistency. It is important to check whether there is a need to change to an older SDK version. More often than not, your best and most secure option is simply to use the latest available version of the .NET runtime.

Liked it? Take a second to support Code Maze on Patreon and get the ad free reading experience!
Become a patron at Patreon!