Merge pull request #17877 from dotnet/publish-21913

Merge master into live

Author: BillWagner

docs/core/tools/dotnet-add-package.md

@@ -13,7 +13,14 @@ ms.date: 02/14/2020
 
 ## Synopsis
 
-`dotnet add [<PROJECT>] package <PACKAGE_NAME> [-h|--help] [-f|--framework] [--interactive] [-n|--no-restore] [--package-directory] [-s|--source] [-v|--version]`
+```dotnetcli
+dotnet add [<PROJECT>] package <PACKAGE_NAME>
+    [-f|--framework <FRAMEWORK>] [--interactive]
+    [-n|--no-restore] [--package-directory <PACKAGE_DIRECTORY>]
+    [-s|--source <SOURCE>] [-v|--version <VERSION>]
+
+dotnet add package -h|--help
+```
 
 ## Description
 

docs/core/tools/dotnet-add-reference.md

@@ -7,17 +7,18 @@ ms.date: 02/14/2020
 
 **This article applies to:** ✔️ .NET Core 2.x SDK and later versions
 
-<!-- todo: uncomment when all CLI commands are reviewed
-[!INCLUDE [topic-appliesto-net-core-all](../../../includes/topic-appliesto-net-core-all.md)]
--->
-
 ## Name
 
 `dotnet add reference` - Adds project-to-project (P2P) references.
 
 ## Synopsis
 
-`dotnet add [<PROJECT>] reference [-f|--framework] <PROJECT_REFERENCES> [-h|--help] [--interactive]`
+```dotnetcli
+dotnet add [<PROJECT>] reference [-f|--framework <FRAMEWORK>]
+     [--interactive] <PROJECT_REFERENCES>
+
+dotnet add reference -h|--help
+```
 
 ## Description
 
@@ -43,14 +44,14 @@ The `dotnet add reference` command provides a convenient option to add project r
 
 ## Options
 
-- **`-h|--help`**
-
-  Prints out a short help for the command.
-
 - **`-f|--framework <FRAMEWORK>`**
 
   Adds project references only when targeting a specific [framework](../../standard/frameworks.md).
 
+- **`-h|--help`**
+
+  Prints out a short help for the command.
+
 - **`--interactive`**
 
   Allows the command to stop and wait for user input or action (for example, to complete authentication). Available since .NET Core 3.0 SDK.

docs/core/tools/dotnet-build-server.md

@@ -15,8 +15,10 @@ ms.date: 02/14/2020
 
 ```dotnetcli
 dotnet build-server shutdown [--msbuild] [--razor] [--vbcscompiler]
-dotnet build-server shutdown [-h|--help]
-dotnet build-server [-h|--help]
+
+dotnet build-server shutdown -h|--help
+
+dotnet build-server -h|--help
 ```
 
 ## Commands

docs/core/tools/dotnet-build.md

@@ -14,11 +14,13 @@ ms.date: 02/14/2020
 ## Synopsis
 
 ```dotnetcli
-dotnet build [<PROJECT>|<SOLUTION>] [-c|--configuration] [-f|--framework] [--force]
-    [--interactive] [--no-dependencies] [--no-incremental] [--no-restore] [--nologo]
-    [-o|--output] [-r|--runtime] [-v|--verbosity] [--version-suffix]
+dotnet build [<PROJECT>|<SOLUTION>] [-c|--configuration <CONFIGURATION>]
+    [-f|--framework <FRAMEWORK>] [--force] [--interactive] [--no-dependencies]
+    [--no-incremental] [--no-restore] [--nologo] [-o|--output <OUTPUT_DIRECTORY>]
+    [-r|--runtime <RUNTIME_IDENTIFIER>] [-v|--verbosity <LEVEL>]
+    [--version-suffix <VERSION_SUFFIX>]
 
-dotnet build [-h|--help]
+dotnet build -h|--help
 ```
 
 ## Description

docs/core/tools/dotnet-clean.md

@@ -14,9 +14,12 @@ ms.date: 02/14/2020
 ## Synopsis
 
 ```dotnetcli
-dotnet clean [<PROJECT>|<SOLUTION>] [-c|--configuration] [-f|--framework] [--interactive]
-    [--nologo] [-o|--output] [-r|--runtime] [-v|--verbosity]
-dotnet clean [-h|--help]
+dotnet clean [<PROJECT>|<SOLUTION>] [-c|--configuration <CONFIGURATION>]
+    [-f|--framework <FRAMEWORK>] [--interactive]
+    [--nologo] [-o|--output <OUTPUT_DIRECTORY>]
+    [-r|--runtime <RUNTIME_IDENTIFIER>] [-v|--verbosity <LEVEL>]
+
+dotnet clean -h|--help
 ```
 
 ## Description

docs/core/tools/dotnet-help.md

@@ -13,7 +13,9 @@ ms.date: 02/14/2020
 
 ## Synopsis
 
-`dotnet help <COMMAND_NAME> [-h|--help]`
+```dotnetcli
+dotnet help <COMMAND_NAME> [-h|--help]
+```
 
 ## Description
 

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

@@ -14,17 +14,28 @@ ms.date: 01/23/2020
 Windows:
 
 ```powershell
-dotnet-install.ps1 [-Channel] [-Version] [-JSonFile] [-InstallDir] [-Architecture]
-    [-Runtime] [-DryRun] [-NoPath] [-Verbose] [-AzureFeed] [-UncachedFeed] [-NoCdn] [-FeedCredential]
-    [-ProxyAddress] [-ProxyUseDefaultCredentials] [-SkipNonVersionedFiles] [-Help]
+dotnet-install.ps1 [-Architecture <ARCHITECTURE>] [-AzureFeed]
+    [-Channel <CHANNEL>] [-DryRun] [-FeedCredential]
+    [-InstallDir <DIRECTORY>] [-JSonFile <JSONFILE>]
+    [-NoCdn] [-NoPath] [-ProxyAddress]
+    [-ProxyUseDefaultCredentials] [-Runtime <RUNTIME>]
+    [-SkipNonVersionedFiles] [-UncachedFeed] [-Verbose]
+    [-Version <VERSION>]
+
+dotnet-install.ps1 -Help
 ```
 
 Linux/macOs:
 
 ```bash
-dotnet-install.sh [--channel] [--version] [--jsonfile] [--install-dir] [--architecture]
-    [--runtime] [--dry-run] [--no-path] [--verbose] [--azure-feed] [--uncached-feed] [--no-cdn] [--feed-credential]
-    [--runtime-id] [--skip-non-versioned-files] [--help]
+dotnet-install.sh  [--architecture <ARCHITECTURE>] [--azure-feed]
+    [--channel <CHANNEL>] [--dry-run] [--feed-credential]
+    [--install-dir <DIRECTORY>] [--jsonfile <JSONFILE>]
+    [--no-cdn] [--no-path] [--runtime <RUNTIME>] [--runtime-id <RID>]
+    [--skip-non-versioned-files] [--uncached-feed] [--verbose]
+    [--version <VERSION>]
+
+dotnet-install.sh --help
 ```
 
 ## Description
@@ -48,6 +59,14 @@ You can install a specific version using the `-Version|--version` argument. The
 
 ## Options
 
+- **`-Architecture|--architecture <ARCHITECTURE>`**
+
+  Architecture of the .NET Core binaries to install. Possible values are `<auto>`, `amd64`, `x64`, `x86`, `arm64`, and `arm`. The default value is `<auto>`, which represents the currently running OS architecture.
+
+- **`-AzureFeed|--azure-feed`**
+
+  Specifies the URL for the Azure feed to the installer. We recommended that you don't change this value. The default value is `https://dotnetcli.azureedge.net/dotnet`.
+
 - **`-Channel|--channel <CHANNEL>`**
 
   Specifies the source channel for the installation. The possible values are:
@@ -59,34 +78,41 @@ You can install a specific version using the `-Version|--version` argument. The
 
   The default value is `LTS`. For more information on .NET support channels, see the [.NET Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) page.
 
-- **`-Version|--version <VERSION>`**
+- **`-DryRun|--dry-run`**
 
-  Represents a specific build version. The possible values are:
+  If set, the script won't perform the installation. Instead, it displays what command line to use to consistently install the currently requested version of the .NET Core CLI. For example, if you specify version `latest`, it displays a link with the specific version so that this command can be used deterministically in a build script. It also displays the binary's location if you prefer to install or download it yourself.
 
-  - `latest` - Latest build on the channel (used with the `-Channel` option).
-  - `coherent` - Latest coherent build on the channel; uses the latest stable package combination (used with Branch name `-Channel` options).
-  - Three-part version in X.Y.Z format representing a specific build version; supersedes the `-Channel` option. For example: `2.0.0-preview2-006120`.
+- **`-FeedCredential|--feed-credential`**
 
-  If not specified, `-Version` defaults to `latest`.
+  Used as a query string to append to the Azure feed. It allows changing the URL to use non-public blob storage accounts.
 
-- **`-JSonFile|--jsonfile <JSONFILE>`**
+- **`-Help|--help`**
 
-  Specifies a path to a [global.json](global-json.md) file that will be used to determine the SDK version. The *global.json* file must have a value for `sdk:version`.
+  Prints out help for the script.
 
 - **`-InstallDir|--install-dir <DIRECTORY>`**
 
   Specifies the installation path. The directory is created if it doesn't exist. The default value is *%LocalAppData%\Microsoft\dotnet*. Binaries are placed directly in this directory.
 
-- **`-Architecture|--architecture <ARCHITECTURE>`**
+- **`-JSonFile|--jsonfile <JSONFILE>`**
 
-  Architecture of the .NET Core binaries to install. Possible values are `<auto>`, `amd64`, `x64`, `x86`, `arm64`, and `arm`. The default value is `<auto>`, which represents the currently running OS architecture.
+  Specifies a path to a [global.json](global-json.md) file that will be used to determine the SDK version. The *global.json* file must have a value for `sdk:version`.
 
-- **`-SharedRuntime|--shared-runtime`**
+- **`-NoCdn|--no-cdn`**
 
-  > [!NOTE]
-  > This parameter is obsolete and may be removed in a future version of the script. The recommended alternative is the `-Runtime|--runtime` option.
+  Disables downloading from the [Azure Content Delivery Network (CDN)](https://docs.microsoft.com/azure/cdn/cdn-overview) and uses the uncached feed directly.
 
-  Installs just the shared runtime bits, not the entire SDK. This option is equivalent to specifying `-Runtime|--runtime dotnet`.
+- **`-NoPath|--no-path`**
+
+  If set, the installation folder isn't exported to the path for the current session. By default, the script modifies the PATH, which makes the .NET Core CLI available immediately after install.
+
+- **`-ProxyAddress`**
+
+  If set, the installer uses the proxy when making web requests. (Only valid for Windows.)
+
+- **`ProxyUseDefaultCredentials`**
+
+  If set, the installer uses the credentials of the current user when using proxy address. (Only valid for Windows.)
 
 - **`-Runtime|--runtime <RUNTIME>`**
 
@@ -96,53 +122,38 @@ You can install a specific version using the `-Version|--version` argument. The
   - `aspnetcore` - the `Microsoft.AspNetCore.App` shared runtime.
   - `windowsdesktop` - the `Microsoft.WindowsDesktop.App` shared runtime.
 
-- **`-DryRun|--dry-run`**
-
-  If set, the script won't perform the installation. Instead, it displays what command line to use to consistently install the currently requested version of the .NET Core CLI. For example, if you specify version `latest`, it displays a link with the specific version so that this command can be used deterministically in a build script. It also displays the binary's location if you prefer to install or download it yourself.
+- **`--runtime-id <RID>`**
 
-- **`-NoPath|--no-path`**
+  Specifies the [runtime identifier](../rid-catalog.md) for which the tools are being installed. Use `linux-x64` for portable Linux. (Only valid for Linux/macOS.)
 
-  If set, the installation folder isn't exported to the path for the current session. By default, the script modifies the PATH, which makes the .NET Core CLI available immediately after install.
+- **`-SharedRuntime|--shared-runtime`**
 
-- **`-Verbose|--verbose`**
+  > [!NOTE]
+  > This parameter is obsolete and may be removed in a future version of the script. The recommended alternative is the `-Runtime|--runtime` option.
 
-  Displays diagnostics information.
+  Installs just the shared runtime bits, not the entire SDK. This option is equivalent to specifying `-Runtime|--runtime dotnet`.
 
-- **`-AzureFeed|--azure-feed`**
+- **`-SkipNonVersionedFiles|--skip-non-versioned-files`**
 
-  Specifies the URL for the Azure feed to the installer. We recommended that you don't change this value. The default value is `https://dotnetcli.azureedge.net/dotnet`.
+  Skips installing non-versioned files, such as *dotnet.exe*, if they already exist.
 
 - **`-UncachedFeed|--uncached-feed`**
 
   Allows changing the URL for the uncached feed used by this installer. We recommended that you don't change this value.
 
-- **`-NoCdn|--no-cdn`**
-
-  Disables downloading from the [Azure Content Delivery Network (CDN)](https://docs.microsoft.com/azure/cdn/cdn-overview) and uses the uncached feed directly.
-
-- **`-FeedCredential|--feed-credential`**
-
-  Used as a query string to append to the Azure feed. It allows changing the URL to use non-public blob storage accounts.
-
-- **`--runtime-id`**
-
-  Specifies the [runtime identifier](../rid-catalog.md) for which the tools are being installed. Use `linux-x64` for portable Linux. (Only valid for Linux/macOS)
-
-- **`-ProxyAddress`**
-
-  If set, the installer uses the proxy when making web requests. (Only valid for Windows)
-
-- **`ProxyUseDefaultCredentials`**
+- **`-Verbose|--verbose`**
 
-  If set, the installer uses the credentials of the current user when using proxy address. (Only valid for Windows)
+  Displays diagnostics information.
 
-- **`-SkipNonVersionedFiles|--skip-non-versioned-files`**
+- **`-Version|--version <VERSION>`**
 
-  Skips installing non-versioned files, such as *dotnet.exe*, if they already exist.
+  Represents a specific build version. The possible values are:
 
-- **`-Help|--help`**
+  - `latest` - Latest build on the channel (used with the `-Channel` option).
+  - `coherent` - Latest coherent build on the channel; uses the latest stable package combination (used with Branch name `-Channel` options).
+  - Three-part version in X.Y.Z format representing a specific build version; supersedes the `-Channel` option. For example: `2.0.0-preview2-006120`.
 
-  Prints out help for the script.
+  If not specified, `-Version` defaults to `latest`.
 
 ## Examples
 

docs/core/tools/dotnet-list-package.md

@@ -14,9 +14,12 @@ ms.date: 02/14/2020
 ## Synopsis
 
 ```dotnetcli
-dotnet list [<PROJECT>|<SOLUTION>] package [--config] [--framework] [--highest-minor] [--highest-patch]
-   [--include-prerelease] [--include-transitive] [--interactive] [--outdated] [--source]
-dotnet list package [-h|--help]
+dotnet list [<PROJECT>|<SOLUTION>] package [--config <SOURCE>]
+    [--framework <FRAMEWORK>] [--highest-minor] [--highest-patch]
+    [--include-prerelease] [--include-transitive] [--interactive]
+    [--outdated] [--source <SOURCE>]
+
+dotnet list package -h|--help
 ```
 
 ## Description

docs/core/tools/dotnet-list-reference.md

@@ -13,7 +13,11 @@ ms.date: 02/14/2020
 
 ## Synopsis
 
-`dotnet list [<PROJECT>|<SOLUTION>] reference [-h|--help]`
+```dotnetcli
+dotnet list [<PROJECT>|<SOLUTION>] reference
+
+dotnet list -h|--help
+```
 
 ## Description
 

docs/core/tools/dotnet-migrate.md

@@ -14,8 +14,12 @@ ms.date: 02/14/2020
 ## Synopsis
 
 ```dotnetcli
-dotnet migrate [<SOLUTION_FILE|PROJECT_DIR>] [--format-report-file-json] [-r|--report-file] [-s|--skip-project-references] [--skip-backup] [-t|--template-file] [-v|--sdk-package-version] [-x|--xproj-file]
-dotnet migrate [-h|--help]
+dotnet migrate [<SOLUTION_FILE|PROJECT_DIR>] [--format-report-file-json <REPORT_FILE>]
+    [-r|--report-file <REPORT_FILE>] [-s|--skip-project-references [Debug|Release]]
+    [--skip-backup] [-t|--template-file <TEMPLATE_FILE>] [-v|--sdk-package-version]
+    [-x|--xproj-file]
+
+dotnet migrate -h|--help
 ```
 
 ## Description