Document workload advertising manifest downloads (#25243)

Co-authored-by: Daniel Plaisted <dsplaisted@gmail.com>

docs/core/tools/dotnet-build.md

@@ -66,6 +66,8 @@ In addition to its options, the `dotnet build` command accepts MSBuild options,
 
 Running `dotnet build` is equivalent to running `dotnet msbuild -restore`; however, the default verbosity of the output is different.
 
+[!INCLUDE [cli-advertising-manifests](../../../includes/cli-advertising-manifests.md)]
+
 ## Arguments
 
 `PROJECT | SOLUTION`

docs/core/tools/dotnet-environment-variables.md

@@ -1,7 +1,7 @@
 ---
 title: Environment variables used by .NET SDK, .NET CLI, and .NET runtime
 description: Learn about the environment variables that you can use to configure the .NET SDK, .NET CLI, and .NET runtime.
-ms.date: 07/19/2021
+ms.date: 07/20/2021
 ---
 # Environment variables used by .NET SDK, .NET CLI, and .NET runtime
 
@@ -94,6 +94,14 @@ Controls diagnostics tracing from the hosting components, such as `dotnet.exe`,
 
 The typical way to get detailed trace information about application startup is to set `COREHOST_TRACE=1` and`COREHOST_TRACEFILE=host_trace.txt` and then run the application. A new file `host_trace.txt` will be created in the current directory with the detailed information.
 
+## DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE
+
+Disables background download of advertising manifests for workloads. Default is `false` - not disabled. If set to `true`, downloading is disabled. For more information, see [Advertising manifests](dotnet-workload-install.md#advertising-manifests).
+
+## DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_INTERVAL_HOURS
+
+Specifies the minimum number of hours between background downloads of advertising manifests for workloads. Default is `24` - no more frequently than once a day. For more information, see [Advertising manifests](dotnet-workload-install.md#advertising-manifests).
+
 ## See also
 
 - [dotnet command](dotnet.md)

docs/core/tools/dotnet-pack.md

@@ -54,6 +54,8 @@ Web projects aren't packable by default. To override the default behavior, add t
 
 [!INCLUDE[dotnet restore note + options](~/includes/dotnet-restore-note-options.md)]
 
+[!INCLUDE [cli-advertising-manifests](../../../includes/cli-advertising-manifests.md)]
+
 ## Arguments
 
 `PROJECT | SOLUTION`

docs/core/tools/dotnet-publish.md

@@ -84,6 +84,8 @@ For more information, see the following resources:
 - [Visual Studio publish profiles (.pubxml) for ASP.NET Core app deployment](/aspnet/core/host-and-deploy/visual-studio-publish-profiles)
 - [dotnet msbuild](dotnet-msbuild.md)
 
+[!INCLUDE [cli-advertising-manifests](../../../includes/cli-advertising-manifests.md)]
+
 ## Arguments
 
 - **`PROJECT|SOLUTION`**

docs/core/tools/dotnet-restore.md

@@ -75,6 +75,8 @@ There are three specific settings that `dotnet restore` ignores:
 
   Support for cross-platform package signature verification was added in the .NET 5.0.100 SDK.
 
+[!INCLUDE [cli-advertising-manifests](../../../includes/cli-advertising-manifests.md)]
+
 ## Arguments
 
 - **`ROOT`**

docs/core/tools/dotnet-run.md

@@ -48,6 +48,8 @@ To run the application, the `dotnet run` command resolves the dependencies of th
 
 [!INCLUDE[dotnet restore note + options](~/includes/dotnet-restore-note-options.md)]
 
+[!INCLUDE [cli-advertising-manifests](../../../includes/cli-advertising-manifests.md)]
+
 ## Options
 
 <!-- markdownlint-disable MD012 -->

docs/core/tools/dotnet-test.md

@@ -1,7 +1,7 @@
 ---
 title: dotnet test command
 description: The dotnet test command is used to execute unit tests in a given project.
-ms.date: 04/29/2020
+ms.date: 07/20/2021
 ---
 # dotnet test
 
@@ -48,6 +48,8 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 
 [!INCLUDE[dotnet restore note](~/includes/dotnet-restore-note.md)]
 
+[!INCLUDE [cli-advertising-manifests](../../../includes/cli-advertising-manifests.md)]
+
 ## Arguments
 
 - **`PROJECT | SOLUTION | DIRECTORY | DLL`**

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

@@ -1,7 +1,7 @@
 ---
 title: dotnet workload install command
 description: The 'dotnet workload install' command installs optional workloads.
-ms.date: 07/08/2021
+ms.date: 07/20/2021
 ---
 # dotnet workload install
 
@@ -14,7 +14,7 @@ ms.date: 07/08/2021
 ## Synopsis
 
 ```dotnetcli
-dotnet workload install <WORKLOAD_ID>
+dotnet workload install <WORKLOAD_ID>...
     [--configfile <FILE>] [--disable-parallel]
     [--download-to-cache <CACHE>] [--from-cache <CACHE>]
     [--ignore-failed-sources] [--include-previews] [--interactive]
@@ -26,21 +26,44 @@ dotnet workload install -?|-h|--help
 
 ## Description
 
-The `dotnet workload install` command installs an *optional workload*. 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).
+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).
 
 Use [dotnet workload search](dotnet-workload-search.md) to learn what workloads are available to install.
 
-The `dotnet workload install` command installs workload packs, which are packaged and hosted on Nuget.org. For macOS and Linux SDK installations that are installed to a protected directory, the command needs to run elevated. On Windows the command doesn't need to run elevated even if the SDK is installed to the *Program Files* directory. For Windows the command uses MSI installers for that location.
+### When to run elevated
 
-The `dotnet workload` commands operate in the context of specific SDK versions. Suppose you have both .NET 6.0.100 SDK and .NET 7.0.100 SDK installed. The `dotnet workload` commands will give different results depending on which SDK version you select. This behavior applies to major and minor version and feature band differences, not to patch version differences. For example, .NET SDK 6.0.101 and 6.0.102 give the same results, whereas 6.0.100 and 6.0.200 give different results.
+For macOS and Linux SDK installations that are installed to a protected directory, the command needs to run elevated (use the `sudo` command). On Windows, the command doesn't need to run elevated even if the SDK is installed to the *Program Files* directory. For Windows, the command uses MSI installers for that location.
 
- The commands provide the `--sdk-version` option to let you select an SDK version other than the one selected by default or by *global.json*.
+### Results vary by SDK version
+
+The `dotnet workload` commands operate in the context of specific SDK versions. Suppose you have both .NET 6.0.100 SDK and .NET 6.0.200 SDK installed. The `dotnet workload` commands will give different results depending on which SDK version you select. This behavior applies to major and minor version and feature band differences, not to patch version differences. For example, .NET SDK 6.0.101 and 6.0.102 give the same results, whereas 6.0.100 and 6.0.200 give different results. You can specify the SDK version by using the [*global.json* file](global-json.md) or the `--sdk-version` option of the `dotnet workload` commands.
+
+### Advertising manifests
+
+The names and versions of the assets that a workload installation requires are maintained in *manifests*. By default, the `dotnet workload install` command downloads the latest available manifests before it installs a workload. The local copy of a manifest then provides the information needed to find and download the assets for a workload.
+
+The `dotnet workload list` command compares the versions of installed workloads with the currently available versions.  When it finds that a version newer than the installed version is available, it advertises that fact in the command output. These newer-version notifications in `dotnet workload list` are available starting in .NET 6 Preview 7.
+
+To enable these notifications, the latest available versions of the manifests are downloaded and stored as *advertising manifests*.  These downloads happen asynchronously in the background when any of the following commands are run.
+
+* [dotnet build](dotnet-build.md)
+* [dotnet pack](dotnet-pack.md)
+* [dotnet publish](dotnet-publish.md)
+* [dotnet restore](dotnet-restore.md)
+* [dotnet run](dotnet-run.md)
+* [dotnet test](dotnet-test.md)
+
+If a command finishes before the manifest download finishes, the download is stopped. The download is tried again the next time one of these commands is run. You can set environment variables to [disable these background downloads](dotnet-environment-variables.md#dotnet_cli_workload_update_notify_disable) or [control their frequency](dotnet-environment-variables.md#dotnet_cli_workload_update_notify_interval_hours). By default, they don't happen more than once a day.
+
+You can prevent the `dotnet workload install` command from doing manifest downloads by using the `--skip-manifest-update` option.
+
+The `dotnet workload update` command also downloads advertising manifests. The downloads are required to learn if an update is available, so there is no option to prevent them from running. However, you can use the `--advertising-manifests-only` option to skip workload updates and only do the manifest downloads. This option is available starting in .NET 6 Preview 7.
 
 ## Arguments
 
-- **`WORKLOAD_ID`**
+- **`WORKLOAD_ID`...**
 
-  The workload ID of the workload to install. Use [dotnet workload search](dotnet-workload-search.md) to learn what workloads are available to install.
+  The workload ID or multiple IDs to install. Use [dotnet workload search](dotnet-workload-search.md) to learn what workloads are available.
 
 ## Options
 

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

@@ -1,7 +1,7 @@
 ---
 title: dotnet workload update command
 description: The 'dotnet workload update' command updates installed workloads.
-ms.date: 07/08/2021
+ms.date: 07/20/2021
 ---
 # dotnet workload update
 
@@ -15,6 +15,7 @@ ms.date: 07/08/2021
 
 ```dotnetcli
 dotnet workload update
+    [--advertising-manifests-only]
     [--configfile <FILE>] [--disable-parallel]
     [--download-to-cache <CACHE>] [--from-cache <CACHE>]
     [--from-previous-sdk] [--ignore-failed-sources]
@@ -35,6 +36,10 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
 
 <!-- markdownlint-disable MD012 -->
 
+- **`--advertising-manifests-only`**
+
+  Downloads [advertising manifests](dotnet-workload-install.md#advertising-manifests) but doesn't update any workloads. Available starting in .NET 6 Preview 7.
+
 [!INCLUDE [config-file](../../../includes/cli-configfile.md)]
 
 - **`--disable-parallel`**

includes/cli-advertising-manifests.md

@@ -0,0 +1,3 @@
+### Workload manifest downloads
+
+When you run this command, it initiates an asynchronous background download of advertising manifests for workloads. If the download is still running when this command finishes, the download is stopped. For more information, see [Advertising manifests](../docs/core/tools/dotnet-workload-install.md#advertising-manifests).