Skip to content

Commit 97f3558

Browse files
tdykstratdykstra
committed
draft
1 parent a354ff9 commit 97f3558

File tree

6 files changed

+167
-5
lines changed

6 files changed

+167
-5
lines changed

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

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: dotnet workload config command
3+
description: The 'dotnet workload config' command determines whether updates should look for workload sets or the latest version of each individual manifest.
4+
ms.date: 09/10/2021
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 mode.
13+
14+
## Synopsis
15+
16+
```dotnetcli
17+
dotnet workload config [--update-mode <workload-set>|<manifests>]
18+
19+
dotnet workload config -?|-h|--help
20+
```
21+
22+
## Description
23+
24+
The `dotnet workload config` command selects workload set update mode or manifests update mode. It can also display the currently selected update mode.
25+
26+
For more information about the `dotnet workload config` command, see [.NET SDK workload sets](dotnet-workload-sets.md).
27+
28+
## Options
29+
30+
[!INCLUDE [help](../../../includes/cli-help.md)]
31+
32+
- **`--update-mode <workload-set>|<manifests>`**
33+
34+
Controls whether updates should look for workload set versions or the latest version of each individual manifest. To display the current mode, specify this option without an argument. For more information, see [.NET SDK workload sets](dotnet-workload-sets.md).
35+
36+
## Examples
37+
38+
- Enable workload set update mode:
39+
40+
```dotnetcli
41+
dotnet workload config --update-mode workload-set
42+
```
43+
44+
- Disable workload set update mode:
45+
46+
```dotnetcli
47+
dotnet workload config --update-mode manifests
48+
```

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

Lines changed: 8 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]
2222
2323
dotnet workload install -?|-h|--help
2424
```
@@ -27,6 +27,8 @@ 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+
Workload versions installed are based the latest workload set or a specified workload set version, not necessarily the latest version available of each individual workload. For more information, see [.NET SDK workload sets](dotnet-workload-sets.md). Workload set update mode is available since 8.0.400 SDK.
31+
3032
Use [dotnet workload search](dotnet-workload-search.md) to learn what workloads are available to install.
3133

3234
### When to run elevated
@@ -88,6 +90,10 @@ The `dotnet workload update` command also downloads advertising manifests. The d
8890

8991
[!INCLUDE [verbosity](../../../includes/cli-verbosity-packages.md)]
9092

93+
- **`--version`**
94+
95+
The workload set version to update to. Available since 8.0.400 SDK. For more information, see [.NET SDK workload sets](dotnet-workload-sets.md).
96+
9197
## Examples
9298

9399
- Install the `maui` workload:

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

Lines changed: 6 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,10 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
5959

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

62+
- **`--version <VERSION>`**
63+
64+
The workload set version to update to. Available since 8.0.400 SDK. For more information, see [.NET SDK workload sets](dotnet-workload-sets.md).
65+
6266
## Example
6367

6468
- Restore workloads needed by MyApp.csproj:

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

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: .NET SDK workload sets
3+
description: "Learn how to use workload sets to control which versions of workloads get installed, updated, and 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 multiple workloads in a project, I want to keep my workload versions in sync so that I can avoid problems that might arise from conflicts betwween versions. Even if I only have one workload, I want to avoid having a workload be updated to a different version when I'm not expecting it.
11+
---
12+
# .NET SDK workload sets
13+
14+
A workload set provides a single version number that represents a group of .NET SDK workloads. This enables you to install and update a combination of workload versions that ship at the same time and are known to work together. Workload sets are published to nuget.org with each release of the .NET SDK, under the package ID `Microsoft.NET.Workloads.<feature band>`
15+
16+
Here are some ways you can use workload sets:
17+
18+
* Update to the latest available workload set version.
19+
* Update to a specific workload set version.
20+
* "Pin" the install command to a specific workload set version.
21+
* Restore to a specific workload set version.
22+
23+
You can also:
24+
25+
* Check a project's current workload set version.
26+
* Update to the latest version of each individual workload, ignoring workload sets.
27+
28+
## Prerequisites
29+
30+
* [.NET 8.0.400 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) or later.
31+
32+
In 8.0.400 SDK, the `dotnet workload` commands are in workload set update mode when it's explicitly selected. 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.
33+
34+
## Update to the latest available workload set version
35+
36+
To update installed workloads to the latest workload set version available on the configured feeds, run these commands:
37+
38+
```dotnetcli
39+
dotnet workload config --update-mode workload-set
40+
dotnet workload update
41+
```
42+
43+
In .NET 9 SDK, workload set update mode is the default, so it isn't necessary to explicitly select it with the `dotnet workload config` command shown here.
44+
45+
## Update to a specific workload set version
46+
47+
Use the `--version` option of the `dotnet workload update` command to specify a workload set version to update to. For example:
48+
49+
```dotnetcli
50+
dotnet workload update --version 8.400.0-preview.0.24219.1.
51+
```
52+
53+
## "Pin" the install command
54+
55+
A `dotnet workload install` command with the `--version` option "pins" the `dotnet workload install` command so that it no longer automatically installs a newer workload set. However, `dotnet workload update` doesn't get pinned. If you run a `dotnet workload update` command without the `--version` option, the command:
56+
57+
* Installs the latest available workload set version.
58+
* "Unpins" the `install` command.
59+
* Stays in workload set update mode.
60+
61+
## Specify the workload set version using global.json
62+
63+
Create a `global.json` file to specify the workload set version for a repository. The format looks like this example:
64+
65+
```json
66+
{
67+
"sdk": {
68+
"workloadVersion": "8.400.0-preview.0.24219.1"
69+
}
70+
}
71+
```
72+
73+
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 will install the workload set version that was established when you switched from manifests update mode to workload sets update mode.
74+
75+
## Ignore workload set versions
76+
77+
To update to the latest version of each individual workload available on the configured feeds, select and use manifests update mode by running these commands:
78+
79+
```dotnetcli
80+
dotnet workload config --update-mode manifests
81+
dotnet workload update
82+
```
83+
84+
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.
85+
86+
## Check the workload set version
87+
88+
To see the current workload set version, run `dotnet workload --version`. If a workload set is installed, you see a version such as `8.0.400-preview.0.24217.2` or `8.0.401`. If there is no workload set version, you see a version in the form of `<feature band>-manifests.<hash>`, such as `8.0.400-manifests.45f976f0`.
89+
90+
## Related content
91+
92+
[dotnet workload command](dotnet-workload.md)
93+
[dotnet workload install](dotnet-workload-install.md)
94+
[dotnet workload update](dotnet-workload-update.md)

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

Lines changed: 7 additions & 1 deletion
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+
If 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.
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,6 +63,10 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
6163

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

66+
- **`--version`**
67+
68+
The workload set version to update to. Available since 8.0.400 SDK. For more information, see [.NET SDK workload sets](dotnet-workload-sets.md).
69+
6470
## Examples
6571

6672
- Update the installed workloads:

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

0 commit comments

Comments
 (0)