dotnet-workload-sets(1)

📦
version 11.0.0~rc3 · 2 versions
  • 11.0.0~rc3 · alpine 3.24, centos-stream 10, centos-stream 9, fedora 43, fedora 44, nixpkgs unstable, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 9.0.17 · fedora 43, ubuntu questing
, in alpine 3.24, centos-stream 10, centos-stream 9, fedora 43, fedora 44, nixpkgs unstable, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 .NET SDK workload sets 💅

okay bestie, welcome to dotnet-workload-sets(1) from the .NET Documentation — pull up a chair, grab a strawberry 🍓, and let me tell you about the single most underrated glow-up in the .NET SDK: workload sets.

So here's the tea ☕: the workload sets feature gives you a version number that represents a whole group of .NET SDK workloads. And the install, update, and restore commands use that number when they're in workload-set update mode. It's giving ✨organized✨. Here's what that buys you:

  • You control the cadence of change for installed workload versions. The alternative mode of operation without using workload sets is called loose manifests update mode. In that mode, workloads get updated automatically as new versions of individual workloads are released onto any configured NuGet feeds. But in workload-set update mode? Workloads stay at a specific workload-set version until you explicitly change that version. No surprise updates, no chaos, immaculate vibes only 💅
  • You can install and update a combination of workload versions that ship at the same time and are known to work together. friendship bracelet energy 🫶
  • You can ensure that everyone on your team is always working on the same workload versions. no more "it works on my machine" 😭
  • You don't have to use a rollback file to specify what workload version you want to be on. bye bestie 👋

Here are some ways you can use workload sets:

  • "Pin" the install command to a specific workload-set version.
  • Update installed workloads to the latest available workload-set version.
  • Update to a specified workload-set version.
  • Specify the workload-set version in global.json.
  • Check your current update mode and workload-set version.

And yes, you can still choose to install, update, or restore to the latest version of each individual workload, ignoring workload sets entirely. your choice, your era 🌸

🎀 Prerequisites 🎀

📌 "Pin" the install command

A dotnet workload install command with the --version option "pins" the install command in workload-set update mode with the specified workload-set version. After that, the command no longer automatically installs the newest workload based on loose manifests. it's committed. it's in a relationship now 💖

To "pin" the install command:

  1. Choose a workload-set version. For example, 9.0.100-preview.7.24414.1.
  2. Choose a workload. For example, aspire.

3.

dotnet workload install aspire --version 9.0.100-preview.7.24414.1

When this command runs:

  • It selects workload-set update mode if that isn't already selected.
  • It gets the workload set that has the specified version.
  • From the workload set, it gets the manifest version of the specified workload.
  • It installs the manifest version of the workload.
  • It stays in workload-set update mode when it's done.
  1. Choose another workload to install, such as maui-ios.

5.

dotnet workload install maui-ios

This command installs the maui-ios workload using the workload version from the workload-set version 9.0.100-preview.7.24414.1, since the preceding install command example pinned that workload set. see? it remembered. iconic behavior 👑

Using --version with either install or update pins install to the specified version, but update is only configured for workload-set update mode, not to a specific workload-set version. So if you then run dotnet workload update without the --version option, the update command:

  • Updates workloads to the latest available workload-set version.
  • "Unpins" the install command.
  • Stays in workload-set update mode.

🦋 Update using latest workload set

To update installed workloads to the latest workload-set version available on the configured feeds, run the following commands:

1.

dotnet workload config --update-mode workload-set

The preceding command is necessary only if you are currently in manifests update mode. If you don't know, check the current update mode. (there's a whole section for that, keep scrolling bestie 👀)

2.

dotnet workload update

In workload-set update mode, this command updates workloads to the latest workload-set version, unless you have specified the workload-set version in global.json.

⭐ Update to a workload-set version

To specify a workload-set version to update to when you're not specifying it in global.json, use the --version option of the update command:

  1. Choose a workload-set version. For example, 8.0.400.

2.

dotnet workload update --version 8.0.400

workload-set update mode will be selected if it wasn't already selected.

🌈 Use global.json for the workload-set version

To use a global.json file to specify the workload-set version for a repository:

  1. Choose a workload-set version. For example, 9.0.100-preview.7.24414.1.
  2. Create a global.json file that looks like the following example:
{
  "sdk": {
    "workloadVersion": "9.0.100-preview.7.24414.1"
  }
}

With the current directory in the same repository and the CLI in workload-set update mode, the install, update, and restore commands install workloads for the specified workload-set version. If you don't have a global.json file and you're in workload-set update mode, the restore command installs the workload-set version that was established when you switched from manifests update mode to workload-set update mode.

If you have a workload-set version in the global.json file, the workload commands are in workload-set mode even if you haven't run the config command or used --version. The global.json file overrides those. To use the --version option in that case, run the command outside of the path containing the global.json file. (yes, that means stepping outside the folder. literally leaving the premises 🚶♀️)

If you don't specify the workload-set version in global.json, you can use the --version option with the restore command. In that case, the restore command selects workload-set update mode before it restores workloads to the specified workload-set version.

In manifests update mode, restore installs or updates workloads to the latest version of each individual workload.

💀 Check the update mode and version

To see the current update mode, run the config command with the --update-mode option without an argument. The mode is either workload-set or manifests. For example:

dotnet workload config --update-mode

workload-set

To see the current workload-set version, run dotnet workload --version. If a workload set is installed, you see a version such as 9.0.100-preview.7.24414.1 or 8.0.402. For example:

dotnet workload --version

9.0.100-preview.7.24414.1

In manifests mode, or if the workload-set version isn't established yet after switching to workload-set update mode, you see a version in the form of <feature band>-manifests.<hash>. For example:

dotnet workload --version

9.0.100-manifests.cf958b56
not me checking my update mode every five minutes like it's a situationship 💀

👑 Choose a workload-set version

Workload sets are published to nuget.org with each release of the .NET SDK, under the package ID Microsoft.NET.Workloads.<feature band>. For a stable version of the SDK, there is always a matching workload-set version. So 8.0.400 SDK can install an 8.0.400 workload set, and 401 can install a 401 set. In general, we recommend that you install the matching workload set for a stable SDK. matching sets, matching energy, that's the rule ✨

For preview releases, find the corresponding workload-set version in the package's README tab. For example, see the README tab for the .NET 9 Preview 7 package (https://www.nuget.org/packages/Microsoft.NET.Workloads.9.0.100-preview.7/9.100.0-preview.7.24414.1#readme-body-tab).

In the future, you'll be able to see a list of workload-set versions and what they contain. (manifesting this feature fr fr 🙏)

🙈 Ignore workload sets

To install, or update to, the latest version of each individual workload available on the configured feeds, select and use manifests update mode by running the workload config command:

dotnet workload config --update-mode manifests

In .NET 8.0.4xx SDK, manifests mode is the default. In this version, you need to select manifests mode explicitly only if you explicitly selected workload-set update mode previously.

🫶 Related content

  • dotnet workload command
  • dotnet workload install
  • dotnet workload update

and that's the whole page, bestie 💜 this came from the .NET Documentation squad, dated 2025-06-13, and it's dotnet-workload-sets(1) — go forth and pin your workloads, you absolute main character 👑✨

📦 where this page comes from