Documentation for Workload Sets feature

docs/core/tools/dotnet-workload-config.md

@@ -0,0 +1,47 @@
+---
+title: dotnet workload config command
+description: "The `dotnet workload config` command selects workload set update mode or manifests update mode. It can also display the currently selected update mode."
+ms.date: 09/10/2021
+---
+# dotnet workload config
+
+**This article applies to:** ✔️ .NET 8.0.400 SDK and later versions
+
+## Name
+
+`dotnet workload config` - Enables or disables workload set update mode.
+
+## Synopsis
+
+```dotnetcli
+dotnet workload config
+[--update-mode [<workload-set>|<manifests>]]
+
+dotnet workload config -?|-h|--help
+```
+
+## Description
+
+For more information about the `dotnet workload config` command, see [.NET SDK workload sets](dotnet-workload-sets.md).
+
+## Options
+
+  [!INCLUDE [help](../../../includes/cli-help.md)]
+
+- **`--update-mode [<workload-set>|<manifests>]`**
+
+  Controls whether updates look for workload set versions or workload versions. To display the current mode, specify this option without an argument. For more information, see [.NET SDK workload sets](dotnet-workload-sets.md).
+
+## Examples
+
+- Enable workload set update mode:
+
+  ```dotnetcli
+  dotnet workload config --update-mode workload-set
+  ```
+
+- Disable workload set update mode:
+
+  ```dotnetcli
+  dotnet workload config --update-mode manifests
+  ```

docs/core/tools/dotnet-workload-install.md

@@ -17,8 +17,8 @@ ms.date: 09/10/2021
 dotnet workload install <WORKLOAD_ID>...
     [--configfile <FILE>] [--disable-parallel]
     [--ignore-failed-sources] [--include-previews] [--interactive]
-    [--no-cache] [--skip-manifest-update]
-    [--source <SOURCE>] [--temp-dir <PATH>] [-v|--verbosity <LEVEL>]
+    [--no-cache] [--skip-manifest-update] [--source <SOURCE>]
+    [--temp-dir <PATH>] [-v|--verbosity <LEVEL>] [--version <VERSION>]
 
 dotnet workload install -?|-h|--help
 ```
@@ -27,6 +27,13 @@ dotnet workload install -?|-h|--help
 
 The `dotnet workload install` command installs one or more *optional workloads*. Optional workloads can be installed on top of the .NET SDK to provide support for various application types, such as [.NET MAUI](/dotnet/maui/what-is-maui) and [Blazor WebAssembly AOT](https://devblogs.microsoft.com/aspnet/asp-net-core-updates-in-net-6-preview-4/#blazor-webassembly-ahead-of-time-aot-compilation).
 
+When the command is in workload set install mode,  workload versions installed are:
+
+* From the latest workload set or a specified workload set version.
+* Might not be the latest version available of each individual workload.
+
+For more information, see [.NET SDK workload sets](dotnet-workload-sets.md). Workload set install mode is available since 8.0.400 SDK.
+
 Use [dotnet workload search](dotnet-workload-search.md) to learn what workloads are available to install.
 
 ### When to run elevated
@@ -88,6 +95,8 @@ The `dotnet workload update` command also downloads advertising manifests. The d
 
 [!INCLUDE [verbosity](../../../includes/cli-verbosity-packages.md)]
 
+[!INCLUDE [version](../../../includes/cli-version.md)]
+
 ## Examples
 
 - Install the `maui` workload:

docs/core/tools/dotnet-workload-restore.md

@@ -17,8 +17,8 @@ ms.date: 09/10/2021
 dotnet workload restore [<PROJECT | SOLUTION>]
     [--configfile <FILE>] [--disable-parallel]
     [--ignore-failed-sources] [--include-previews] [--interactive]
-    [--no-cache] [--skip-manifest-update]
-    [-s|--source <SOURCE>] [--temp-dir <PATH>] [-v|--verbosity <LEVEL>]
+    [--no-cache] [--skip-manifest-update] [-s|--source <SOURCE>] 
+    [--temp-dir <PATH>] [-v|--verbosity <LEVEL>] [--version <VERSION>]
 
 dotnet workload restore -?|-h|--help
 ```
@@ -59,6 +59,8 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
 
 [!INCLUDE [verbosity](../../../includes/cli-verbosity-minimal.md)]
 
+[!INCLUDE [version](../../../includes/cli-version.md)]
+
 ## Example
 
 - Restore workloads needed by MyApp.csproj:

docs/core/tools/dotnet-workload-sets.md

@@ -0,0 +1,163 @@
+---
+title: .NET SDK workload sets
+description: "Learn how to use workload sets to control which versions of workloads get installed, updated, or restored."
+author: tdykstra
+ms.author: tdykstra
+ms.service: dotnet
+ms.topic: how-to
+ms.date: 08/02/2024
+
+#customer intent: As a developer using optional workloads, I want to keep my workload versions in sync so that I can avoid conflicts betwween versions. I also want to avoid unexpected workload updates, so that I can avoid disruptions in development.
+---
+<!--https://aka.ms/patterns-feedback-->
+
+# .NET SDK workload sets
+
+The *workload sets* feature provides a version number that represents a group of .NET SDK workloads. The [install](dotnet-workload-install.md), [update](dotnet-workload-update.md), and [restore](dotnet-workload-restore.md) commands use this number in *workload set update mode* to provide the following benefits:
+
+* You get control of 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. So workloads stay at the same manifest version, which is specified by the workload set.
+* 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.
+
+<!--Workload sets are published to nuget.org with each release of the .NET SDK, under the package ID `Microsoft.NET.Workloads.<feature band>`-->
+
+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.
+* Install or update to a specified workload set version.
+* Restore to a specific workload set version using global.json.
+* Check your current update mode and workload set version.
+
+And you can still choose to install or update to the latest version of each individual workload, ignoring workload sets.
+
+## Prerequisites
+
+* [.NET 8.0.400 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) or later.
+
+  In 8.0.400 SDK, the `dotnet workload` commands are in workload set update mode only when it's explicitly selected. Starting in [.NET 9 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), `dotnet workload` commands are in workload set update mode by default.
+
+## "Pin" the install command
+<!--If this heading changes, update the link in \docs\includes\cli-version.md-->
+
+A `dotnet workload install` command with the `--version` option "pins" the `install` command in workload set update mode with the specified workload set version. 
+<!--todo: install without --version in workload set update mode pins to latest workload set?-->
+The command no longer automatically installs the newest workload based on loose manifests. For example:
+
+1. ```dotnetcli
+   dotnet workload install aspire --version 9.0.100-preview.7.24414.1
+   ```
+
+   When this command runs:
+
+   * It gets the workload set with 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. ```dotnetcli
+   dotnet workload install maui-ios
+   ```
+
+   This command installs 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 pinned to workload set update mode, not to a 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. ```dotnetcli
+   dotnet workload config --update-mode workload-set
+   ```
+
+   The preceding command is necessary only if you are currently in manifests update mode. If that isn't known, [check the current update mode](#check-the-update-mode-and-version). Workload set update mode is the default starting in .NET 9 SDK.
+
+1. ```dotnetcli
+   dotnet workload update
+   ```
+
+   This command updates workloads to the latest workload set version.
+
+## Update to a workload set version
+
+To specify a workload set version to update to, use the `--version` option of the `update` command. For example:
+
+```dotnetcli
+dotnet workload update --version 8.0.400
+```
+
+Workload set update mode will be selected if it wasn't already selected.
+
+## Restore workloads using global.json
+
+Create a `global.json` file to specify the workload set version for the restore command for a repository. The format looks like this example:
+
+```json
+{
+  "sdk": {
+    "workloadVersion": "9.0.100-preview.7.24414.1"
+  }
+}
+```
+
+With the current directory in the same repository, `dotnet workload restore` installs 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 sets update mode.
+<!--todo:what about if it's SDK 9 so you defaulted to workload set update mode, and you never established a workload set version -- does it go for latest available then?-->
+<!--todo:if you're in manifests update mode, you stay in that mode and it doesn't seem to do a workload set update(?)-->
+
+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.
+
+## 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:
+
+```dotnetcli
+dotnet workload config --update-mode manifests
+```
+
+In .NET 8.0.4xx SDK, manifests mode is the default. You need to select manifests mode explicitly only if you explicitly selected workload set update mode.
+
+## Check the update mode and version
+
+To see the current update mode, run the `config` command with the `--update-mode` option without an argument. For example:
+
+```dotnetcli
+dotnet workload config --update-mode
+```
+
+```output
+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.401. For example:
+
+```dotnetcli
+dotnet workload --version
+```
+
+```output
+9.0.100-preview.7.24414.1
+```
+
+If there is no workload set version, you see a version in the form of `<feature band>-manifests.<hash>`. For example:
+
+```dotnetcli
+dotnet workload --version
+```
+
+```output
+9.0.100-manifests.cf958b56
+```
+
+## Related content
+
+[dotnet workload command](dotnet-workload.md)
+[dotnet workload install](dotnet-workload-install.md)
+[dotnet workload update](dotnet-workload-update.md)

docs/core/tools/dotnet-workload-update.md

@@ -20,7 +20,7 @@ dotnet workload update
     [--from-previous-sdk] [--ignore-failed-sources]
     [--include-previews] [--interactive] [--no-cache]
     [-s|--source <SOURCE>] [--temp-dir <PATH>]
-    [-v|--verbosity <LEVEL>]
+    [-v|--verbosity <LEVEL>] [--version]
 
 dotnet workload update -?|-h|--help
 ```
@@ -29,6 +29,8 @@ dotnet workload update -?|-h|--help
 
 The `dotnet workload update` command updates all installed workloads to the newest available versions. It queries Nuget.org for updated workload manifests. It then updates local manifests, downloads new versions of the installed workloads, and removes all old versions of each workload.
 
+When the command is in workload set mode, workloads are updated according to the workload set version, not the latest version of each individual workload. For more information, see [.NET SDK workload sets](dotnet-workload-sets.md). Workload set mode is available since 8.0.400 SDK.
+
 For more information about the `dotnet workload` commands, see the [dotnet workload install](dotnet-workload-install.md#description) command.
 
 ## Options
@@ -61,10 +63,20 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
 
 [!INCLUDE [verbosity](../../../includes/cli-verbosity-packages.md)]
 
+[!INCLUDE [version](../../../includes/cli-version.md)]
+
 ## Examples
 
-- Update the installed workloads:
+- Update the installed workloads to the latest version of each individual workload:
+
+  ```dotnetcli
+  dotnet workload config --update-mode manifests
+  dotnet workload update
+  ```
+
+- Update the installed workloads to the latest workload set version:
 
   ```dotnetcli
+  dotnet workload config --update-mode workload-set
   dotnet workload update
   ```

docs/core/tools/dotnet-workload.md

@@ -25,6 +25,10 @@ The `dotnet workload` command provides commands for working with .NET workloads.
 
 ## Options
 
+- **`--version`**
+
+  Displays the current workload set version.
+
 - **`--info`**
 
   Prints out detailed information about installed workloads, including their installation source, manifest version, manifest path, and install type.

docs/navigate/tools-diagnostics/toc.yml

@@ -233,6 +233,10 @@ items:
             items:
               - name: dotnet workload
                 href: ../../core/tools/dotnet-workload.md
+              - name: dotnet workload sets
+                href: ../../core/tools/dotnet-workload-sets.md
+              - name: dotnet workload config
+                href: ../../core/tools/dotnet-workload-config.md
               - name: dotnet workload install
                 href: ../../core/tools/dotnet-workload-install.md
               - name: dotnet workload list

includes/cli-version.md

@@ -0,0 +1,13 @@
+---
+author: tdykstra
+ms.author: tdykstra
+ms.date: 08/12/2024
+ms.topic: include
+---
+- **`--version`**
+
+  The workload set version to install or update to. Available since 8.0.400 SDK. For more information, see [.NET SDK workload sets](../docs/core/tools/dotnet-workload-sets.md), especially these sections:
+
+  * ["Pin" the install command](../docs/core/tools/dotnet-workload-sets.md#pin-the-install-command)
+  * [Update to a specific workload set version](../docs/core/tools/dotnet-workload-sets.md#update-to-a-workload-set-version)
+  * [Check the update mode and version](../docs/core/tools/dotnet-workload-sets.md#check-the-update-mode-and-version)