.NET SDK workload sets

  • Article

The workload sets feature provides a version number that represents a group of .NET SDK workloads. The install, update, and restore commands use this number in workload-set update mode to provide the following benefits:

  • 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 this mode, workloads are updated automatically as new versions of individual workloads are released onto any configured NuGet feeds. In workload-set update mode, workloads stay at a specific workload-set version until you explicitly change that version.
  • You can install and update a combination of workload versions that ship at the same time and are known to work together.
  • You can ensure that everyone on your team is always working on the same workload versions.
  • You don't have to use a rollback file to specify what workload version you want to be on.

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 you can still choose to install, update, or restore to the latest version of each individual workload, ignoring workload sets.

Prerequisites

  • .NET 8.0.400 SDK or later.

    In 8.0.400 SDK, the dotnet workload commands are in workload-set update mode only when it's explicitly selected.

"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. The command no longer automatically installs the newest workload based on loose manifests.

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.

  4. 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.

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. 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.

  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.

If you don't specify the workload-set version in global.json, you can use the --version option with the restore comand. 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

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.

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.

In the future, you'll be able to see a list of workload-set versions and what they contain.

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