Skip to content

Commit 4f7d70b

Browse files
tdykstratdykstra
authored
Documentation for Workload Sets feature (#42109)
1 parent 3a5c16b commit 4f7d70b

File tree

9 files changed

+276
-6
lines changed

9 files changed

+276
-6
lines changed

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

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: dotnet workload config command
3+
description: "The `dotnet workload config` command selects workload set update mode or manifests update mode. It can also display the currently selected update mode."
4+
ms.date: 08/15/2024
5+
---
6+
# dotnet workload config
7+
8+
**This article applies to:** ✔️ .NET 8.0.400 SDK and later versions
9+
10+
## Name
11+
12+
`dotnet workload config` - Enables or disables workload-set update mode.
13+
14+
## Synopsis
15+
16+
```dotnetcli
17+
dotnet workload config
18+
[--update-mode [<workload-set>|<manifests>]]
19+
20+
dotnet workload config -?|-h|--help
21+
```
22+
23+
## Description
24+
25+
For more information about the `dotnet workload config` command, see [.NET SDK workload sets](dotnet-workload-sets.md).
26+
27+
## Options
28+
29+
[!INCLUDE [help](../../../includes/cli-help.md)]
30+
31+
- **`--update-mode [<workload-set>|<manifests>]`**
32+
33+
Controls whether updates look for workload set versions or individual manifest versions. To display the current mode, specify this option without an argument. For more information, see [.NET SDK workload sets](dotnet-workload-sets.md).
34+
35+
## Examples
36+
37+
- Enable workload-set update mode:
38+
39+
```dotnetcli
40+
dotnet workload config --update-mode workload-set
41+
```
42+
43+
- Disable workload-set update mode:
44+
45+
```dotnetcli
46+
dotnet workload config --update-mode manifests
47+
```

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

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ ms.date: 09/10/2021
1717
dotnet workload install <WORKLOAD_ID>...
1818
[--configfile <FILE>] [--disable-parallel]
1919
[--ignore-failed-sources] [--include-previews] [--interactive]
20-
[--no-cache] [--skip-manifest-update]
21-
[--source <SOURCE>] [--temp-dir <PATH>] [-v|--verbosity <LEVEL>]
20+
[--no-cache] [--skip-manifest-update] [--source <SOURCE>]
21+
[--temp-dir <PATH>] [-v|--verbosity <LEVEL>] [--version <VERSION>]
2222
2323
dotnet workload install -?|-h|--help
2424
```
@@ -27,6 +27,13 @@ dotnet workload install -?|-h|--help
2727

2828
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).
2929

30+
When the command is in `workload-set` update mode, workload versions installed:
31+
32+
* Are from the latest workload set or a workload set version specified in a global.json or `--version` option.
33+
* Might not be the latest version available of each individual workload. For example, the `install` command won't install a newer workload set if you previously used the `--version` flag.
34+
35+
For more information, see [.NET SDK workload sets](dotnet-workload-sets.md). `workload-set` update mode is available since 8.0.400 SDK.
36+
3037
Use [dotnet workload search](dotnet-workload-search.md) to learn what workloads are available to install.
3138

3239
### When to run elevated
@@ -88,6 +95,8 @@ The `dotnet workload update` command also downloads advertising manifests. The d
8895

8996
[!INCLUDE [verbosity](../../../includes/cli-verbosity-packages.md)]
9097

98+
[!INCLUDE [version](../../../includes/cli-version.md)]
99+
91100
## Examples
92101

93102
- Install the `maui` workload:

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ ms.date: 09/10/2021
1717
dotnet workload restore [<PROJECT | SOLUTION>]
1818
[--configfile <FILE>] [--disable-parallel]
1919
[--ignore-failed-sources] [--include-previews] [--interactive]
20-
[--no-cache] [--skip-manifest-update]
21-
[-s|--source <SOURCE>] [--temp-dir <PATH>] [-v|--verbosity <LEVEL>]
20+
[--no-cache] [--skip-manifest-update] [-s|--source <SOURCE>]
21+
[--temp-dir <PATH>] [-v|--verbosity <LEVEL>] [--version <VERSION>]
2222
2323
dotnet workload restore -?|-h|--help
2424
```
@@ -59,6 +59,8 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
5959

6060
[!INCLUDE [verbosity](../../../includes/cli-verbosity-minimal.md)]
6161

62+
[!INCLUDE [version](../../../includes/cli-version.md)]
63+
6264
## Example
6365

6466
- Restore workloads needed by MyApp.csproj:

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

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: .NET SDK workload sets
3+
description: "Learn how to use workload sets to control which versions of workloads get installed, updated, or restored."
4+
author: tdykstra
5+
ms.author: tdykstra
6+
ms.service: dotnet
7+
ms.topic: how-to
8+
ms.date: 08/02/2024
9+
10+
#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.
11+
---
12+
# .NET SDK workload sets
13+
14+
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:
15+
16+
* 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.
17+
* You can install and update a combination of workload versions that ship at the same time and are known to work together.
18+
* You can ensure that everyone on your team is always working on the same workload versions.
19+
* You don't have to use a rollback file to specify what workload version you want to be on.
20+
21+
Here are some ways you can use workload sets:
22+
23+
* "Pin" the `install` command to a specific workload-set version.
24+
* Update installed workloads to the latest available workload-set version.
25+
* Update to a specified workload-set version.
26+
* Specify the workload-set version in global.json.
27+
* Check your current update mode and workload-set version.
28+
29+
And you can still choose to install, update, or restore to the latest version of each individual workload, ignoring workload sets.
30+
31+
## Prerequisites
32+
33+
* [.NET 8.0.400 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) or later.
34+
35+
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.-->
36+
37+
## "Pin" the install command
38+
39+
A `dotnet workload install` command with the `--version` option "pins" the `install` command in `workload-set` update mode with the specified workload-set version.
40+
The command no longer automatically installs the newest workload based on loose manifests.
41+
42+
To "pin" the `install` command:
43+
44+
1. [Choose a workload-set version](#choose-a-workload-set-version). For example, `9.0.100-preview.7.24414.1`.
45+
46+
1. [Choose a workload](dotnet-workload-search.md). For example, `aspire`.
47+
48+
1. ```dotnetcli
49+
dotnet workload install aspire --version 9.0.100-preview.7.24414.1
50+
```
51+
52+
When this command runs:
53+
54+
* It selects `workload-set` update mode if that isn't already selected.
55+
* It gets the workload set that has the specified version.
56+
* From the workload set, it gets the manifest version of the specified workload.
57+
* It installs the manifest version of the workload.
58+
* It stays in `workload-set` update mode when it's done.
59+
60+
1. Choose another workload to install, such as `maui-ios`.
61+
62+
1. ```dotnetcli
63+
dotnet workload install maui-ios
64+
```
65+
66+
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.
67+
68+
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:
69+
70+
* Updates workloads to the latest available workload-set version.
71+
* "Unpins" the `install` command.
72+
* Stays in `workload-set` update mode.
73+
74+
## Update using latest workload set
75+
76+
To update installed workloads to the latest workload-set version available on the configured feeds, run the following commands:
77+
78+
1. ```dotnetcli
79+
dotnet workload config --update-mode workload-set
80+
```
81+
82+
The preceding command is necessary only if you are currently in manifests update mode. If you don't know, [check the current update mode](#check-the-update-mode-and-version).
83+
84+
1. ```dotnetcli
85+
dotnet workload update
86+
```
87+
88+
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.
89+
90+
## Update to a workload-set version
91+
92+
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:
93+
94+
1. [Choose a workload-set version](#choose-a-workload-set-version). For example, `8.0.400`.
95+
96+
1. ```dotnetcli
97+
dotnet workload update --version 8.0.400
98+
```
99+
100+
`workload-set` update mode will be selected if it wasn't already selected.
101+
102+
## Use global.json for the workload-set version
103+
104+
To use a `global.json` file to specify the workload-set version for a repository:
105+
106+
1. [Choose a workload-set version](#choose-a-workload-set-version). For example, `9.0.100-preview.7.24414.1`.
107+
108+
1. Create a `global.json` file that looks like the following example:
109+
110+
```json
111+
{
112+
"sdk": {
113+
"workloadVersion": "9.0.100-preview.7.24414.1"
114+
}
115+
}
116+
```
117+
118+
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.
119+
<!--If you're using SDK 9, you defaulted to `workload-set` update mode, and you might not have established a workload-set version. In that case, `restore` installs the latest workload set available on the configured feeds.-->
120+
121+
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.
122+
To use the `--version` option in that case, run the command outside of the path containing the global.json file.
123+
124+
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.
125+
126+
In manifests update mode, `restore` installs or updates workloads to the latest version of each individual workload.
127+
128+
## Check the update mode and version
129+
130+
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:
131+
132+
```dotnetcli
133+
dotnet workload config --update-mode
134+
```
135+
136+
```output
137+
workload-set
138+
```
139+
140+
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:
141+
142+
```dotnetcli
143+
dotnet workload --version
144+
```
145+
146+
```output
147+
9.0.100-preview.7.24414.1
148+
```
149+
150+
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:
151+
152+
```dotnetcli
153+
dotnet workload --version
154+
```
155+
156+
```output
157+
9.0.100-manifests.cf958b56
158+
```
159+
160+
## Choose a workload-set version
161+
162+
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, we plan on always having a matching workload-set version. So 8.0.400 SDK can install an 8.0.400 workload set, 401 can install a 401 set. In general, we recommend that you install the matching workload set for a stable SDK.
163+
164+
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).
165+
166+
This is a preview release. In the future we'll give you ways to list workload set versions to see what's available and what they contain.
167+
168+
## Ignore workload sets
169+
170+
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:
171+
172+
```dotnetcli
173+
dotnet workload config --update-mode manifests
174+
```
175+
176+
In .NET 8.0.4xx SDK, manifests mode is the default. You need to select manifests mode explicitly only if you earlier explicitly selected `workload-set` update mode.
177+
178+
## Related content
179+
180+
* [dotnet workload command](dotnet-workload.md)
181+
* [dotnet workload install](dotnet-workload-install.md)
182+
* [dotnet workload update](dotnet-workload-update.md)

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

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ dotnet workload update
2020
[--from-previous-sdk] [--ignore-failed-sources]
2121
[--include-previews] [--interactive] [--no-cache]
2222
[-s|--source <SOURCE>] [--temp-dir <PATH>]
23-
[-v|--verbosity <LEVEL>]
23+
[-v|--verbosity <LEVEL>] [--version]
2424
2525
dotnet workload update -?|-h|--help
2626
```
@@ -29,6 +29,8 @@ dotnet workload update -?|-h|--help
2929

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

32+
When the command is in `workload-set` update 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.
33+
3234
For more information about the `dotnet workload` commands, see the [dotnet workload install](dotnet-workload-install.md#description) command.
3335

3436
## Options
@@ -61,10 +63,20 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
6163

6264
[!INCLUDE [verbosity](../../../includes/cli-verbosity-packages.md)]
6365

66+
[!INCLUDE [version](../../../includes/cli-version.md)]
67+
6468
## Examples
6569

66-
- Update the installed workloads:
70+
- Update the installed workloads to the latest version of each individual workload:
71+
72+
```dotnetcli
73+
dotnet workload config --update-mode manifests
74+
dotnet workload update
75+
```
76+
77+
- Update the installed workloads to the latest workload set version:
6778

6879
```dotnetcli
80+
dotnet workload config --update-mode workload-set
6981
dotnet workload update
7082
```

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ The `dotnet workload` command provides commands for working with .NET workloads.
2525

2626
## Options
2727

28+
- **`--version`**
29+
30+
Displays the current workload set version.
31+
2832
- **`--info`**
2933

3034
Prints out detailed information about installed workloads, including their installation source, manifest version, manifest path, and install type.

‎docs/core/tools/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,7 @@ The following commands are installed by default:
102102
### Workload management commands
103103

104104
- [`workload`](dotnet-workload.md) (Available since .NET 7 SDK)
105+
- [`workload config`](dotnet-workload-config.md) (Available since .NET 8.0.400 SDK)
105106
- [`workload install`](dotnet-workload-install.md) (Available since .NET 6 SDK)
106107
- [`workload list`](dotnet-workload-list.md) (Available since .NET 6 SDK)
107108
- [`workload update`](dotnet-workload-update.md) (Available since .NET 6 SDK)

‎docs/navigate/tools-diagnostics/toc.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,10 @@ items:
233233
items:
234234
- name: dotnet workload
235235
href: ../../core/tools/dotnet-workload.md
236+
- name: dotnet workload sets
237+
href: ../../core/tools/dotnet-workload-sets.md
238+
- name: dotnet workload config
239+
href: ../../core/tools/dotnet-workload-config.md
236240
- name: dotnet workload install
237241
href: ../../core/tools/dotnet-workload-install.md
238242
- name: dotnet workload list

‎includes/cli-version.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
author: tdykstra
3+
ms.author: tdykstra
4+
ms.date: 08/12/2024
5+
ms.topic: include
6+
---
7+
- **`--version`**
8+
9+
The workload set version to install or update to. If you specify the workload-set version in global.json, you can't use the `--version` option to specify the workload-set version. To make it possible to use the `--version` option in that case, run the command outside of the path containing the global.json file. Available since 8.0.400 SDK. For more information, see [.NET SDK workload sets](../docs/core/tools/dotnet-workload-sets.md).

0 commit comments

Comments
 (0)