diff --git a/docs/core/tools/dotnet-workload-config.md b/docs/core/tools/dotnet-workload-config.md new file mode 100644 index 0000000000000..b18bb9c935dff --- /dev/null +++ b/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: 08/15/2024 +--- +# 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 [|]] + +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 [|]`** + + 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). + +## 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 + ``` diff --git a/docs/core/tools/dotnet-workload-install.md b/docs/core/tools/dotnet-workload-install.md index 8d237eb1b9086..bf722ba093403 100644 --- a/docs/core/tools/dotnet-workload-install.md +++ b/docs/core/tools/dotnet-workload-install.md @@ -17,8 +17,8 @@ ms.date: 09/10/2021 dotnet workload install ... [--configfile ] [--disable-parallel] [--ignore-failed-sources] [--include-previews] [--interactive] - [--no-cache] [--skip-manifest-update] - [--source ] [--temp-dir ] [-v|--verbosity ] + [--no-cache] [--skip-manifest-update] [--source ] + [--temp-dir ] [-v|--verbosity ] [--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` update mode, workload versions installed: + +* Are from the latest workload set or a workload set version specified in a global.json or `--version` option. +* 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. + +For more information, see [.NET SDK workload sets](dotnet-workload-sets.md). `workload-set` update 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: diff --git a/docs/core/tools/dotnet-workload-restore.md b/docs/core/tools/dotnet-workload-restore.md index 89dbee4f7d366..d14b826a3a73f 100644 --- a/docs/core/tools/dotnet-workload-restore.md +++ b/docs/core/tools/dotnet-workload-restore.md @@ -17,8 +17,8 @@ ms.date: 09/10/2021 dotnet workload restore [] [--configfile ] [--disable-parallel] [--ignore-failed-sources] [--include-previews] [--interactive] - [--no-cache] [--skip-manifest-update] - [-s|--source ] [--temp-dir ] [-v|--verbosity ] + [--no-cache] [--skip-manifest-update] [-s|--source ] + [--temp-dir ] [-v|--verbosity ] [--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: diff --git a/docs/core/tools/dotnet-workload-sets.md b/docs/core/tools/dotnet-workload-sets.md new file mode 100644 index 0000000000000..29348d738dee0 --- /dev/null +++ b/docs/core/tools/dotnet-workload-sets.md @@ -0,0 +1,182 @@ +--- +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. +--- +# .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 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](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. + +## "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](#choose-a-workload-set-version). For example, `9.0.100-preview.7.24414.1`. + +1. [Choose a workload](dotnet-workload-search.md). For example, `aspire`. + +1. ```dotnetcli + 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`. + +1. ```dotnetcli + 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. ```dotnetcli + 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](#check-the-update-mode-and-version). + +1. ```dotnetcli + 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](#choose-a-workload-set-version). For example, `8.0.400`. + +1. ```dotnetcli + 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](#choose-a-workload-set-version). For example, `9.0.100-preview.7.24414.1`. + +1. Create a `global.json` file that looks like the following example: + + ```json + { + "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: + +```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.402. For example: + +```dotnetcli +dotnet workload --version +``` + +```output +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 `-manifests.`. For example: + +```dotnetcli +dotnet workload --version +``` + +```output +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.`. 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. + +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). + +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. + +## 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 earlier explicitly selected `workload-set` update mode. + +## Related content + +* [dotnet workload command](dotnet-workload.md) +* [dotnet workload install](dotnet-workload-install.md) +* [dotnet workload update](dotnet-workload-update.md) diff --git a/docs/core/tools/dotnet-workload-update.md b/docs/core/tools/dotnet-workload-update.md index f0694bc7fd588..3f35341a30726 100644 --- a/docs/core/tools/dotnet-workload-update.md +++ b/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 ] [--temp-dir ] - [-v|--verbosity ] + [-v|--verbosity ] [--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` 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. + 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 ``` diff --git a/docs/core/tools/dotnet-workload.md b/docs/core/tools/dotnet-workload.md index 639d68500d4cf..4070624d2f8d8 100644 --- a/docs/core/tools/dotnet-workload.md +++ b/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. diff --git a/docs/core/tools/index.md b/docs/core/tools/index.md index 856a2b790bd2a..b609ae6a84eae 100644 --- a/docs/core/tools/index.md +++ b/docs/core/tools/index.md @@ -102,6 +102,7 @@ The following commands are installed by default: ### Workload management commands - [`workload`](dotnet-workload.md) (Available since .NET 7 SDK) +- [`workload config`](dotnet-workload-config.md) (Available since .NET 8.0.400 SDK) - [`workload install`](dotnet-workload-install.md) (Available since .NET 6 SDK) - [`workload list`](dotnet-workload-list.md) (Available since .NET 6 SDK) - [`workload update`](dotnet-workload-update.md) (Available since .NET 6 SDK) diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index df485675da45c..8950d9afa2933 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/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 diff --git a/includes/cli-version.md b/includes/cli-version.md new file mode 100644 index 0000000000000..228317db2d433 --- /dev/null +++ b/includes/cli-version.md @@ -0,0 +1,9 @@ +--- +author: tdykstra +ms.author: tdykstra +ms.date: 08/12/2024 +ms.topic: include +--- +- **`--version`** + + 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).