Update .NET CLI command docs to reflect support for @ symbol (#49872)

meaghanlewis · gewarren · Copilot · web-flow · commit 7d1b51866406 · 2025-11-14T11:02:34.000-08:00
* Update .NET CLI command docs to reflect support for @ symbol

* Update documentation to replace "at symbol" with "character" for clarity

* Apply suggestions from code review

Co-authored-by: Genevieve Warren &lt;24882762+gewarren@users.noreply.github.com&gt;
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* Apply suggestions from code review

---------

Co-authored-by: Genevieve Warren &lt;24882762+gewarren@users.noreply.github.com&gt;
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/docs/core/tools/dotnet-new-install.md b/docs/core/tools/dotnet-new-install.md
@@ -1,11 +1,11 @@
 ---
 title: dotnet new install
 description: The dotnet new install command installs a template package.
-ms.date: 04/15/2022
+ms.date: 11/12/2025
 ---
 # dotnet new install
 
-**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
+**This article applies to:** ✔️ .NET 6 SDK and later versions
 
 ## Name
 
@@ -20,7 +20,7 @@ dotnet new install <PATH|NUGET_ID>  [--interactive] [--add-source|--nuget-source
 
 ## Description
 
-The `dotnet new install` command installs a template package from the `PATH` or `NUGET_ID` provided. If you want to install a specific version or prerelease version of a template package, specify the version in the format `<package-name>::<package-version>`. By default, `dotnet new` passes \* for the version, which represents the latest stable package version. For more information, see the [Examples](#examples) section.
+The `dotnet new install` command installs a template package from the `PATH` or `NUGET_ID` provided. If you want to install a specific version or prerelease version of a template package, specify the version in the format `<package-name>@<package-version>`. (The colon separator `::` was deprecated in favor of the `@` character in .NET 9.0.200 SDK.) By default, `dotnet new` passes \* for the version, which represents the latest stable package version. For more information, see the [Examples](#examples) section.
 
 If a version of the template package was already installed when you run this command, the template package will be updated to the specified version. If no version is specified, the package is updated to the latest stable version.
 Starting with .NET SDK 6.0.100, if the argument specifies the version, and that version of the NuGet package is already installed, it won't be reinstalled.
@@ -50,7 +50,7 @@ Starting with .NET SDK 6.0.100, installed template packages are available in lat
 - **`<PATH|NUGET_ID>`**
 
   The folder on the file system or the NuGet package identifier to install the template package from. `dotnet new` attempts to install the NuGet package from the NuGet sources available for the current working directory and the sources specified via the `--add-source` option.
-  If you want to install a specific version or prerelease version of a template package from NuGet source, specify the version in the format `<package-name>::<package-version>`.
+  If you want to install a specific version or prerelease version of a template package from NuGet source, specify the version in the format `<package-name>@<package-version>`. (The colon separator `::` was deprecated in favor of the `@` character in .NET 9.0.200 SDK.)
 
 ## Options
 
@@ -91,13 +91,13 @@ Starting with .NET SDK 6.0.100, installed template packages are available in lat
 - Install version 2.0 of the SPA templates for ASP.NET Core:
 
   ```dotnetcli
-  dotnet new install Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0
+  dotnet new install Microsoft.DotNet.Web.Spa.ProjectTemplates@2.0.0
   ```
 
 - Install version 2.0 of the SPA templates for ASP.NET Core from a custom NuGet source using interactive mode:
 
   ```dotnetcli
-  dotnet new install Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0 --add-source "https://api.my-custom-nuget.com/v3/index.json" --interactive
+  dotnet new install Microsoft.DotNet.Web.Spa.ProjectTemplates@2.0.0 --add-source "https://api.my-custom-nuget.com/v3/index.json" --interactive
   ```
 
 ## See also
diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md
@@ -1,7 +1,7 @@
 ---
 title: dotnet tool install command
 description: The dotnet tool install command installs the specified .NET tool on your machine.
-ms.date: 10/28/2025
+ms.date: 11/12/2025
 ---
 # dotnet tool install
 
@@ -94,6 +94,8 @@ For more information, see [Install a local tool](global-tools.md#install-a-local
 
   Name/ID of the NuGet package that contains the .NET tool to install.
 
+  Starting in .NET 10.0.100 SDK, use the name/ID, and version separated by `@` to install a .NET tool.
+
 ## Options
 
 [!INCLUDE [allow-downgrade](../../../includes/cli-allow-downgrade.md)]
@@ -201,10 +203,18 @@ For more information, see [Install a local tool](global-tools.md#install-a-local
 
   Installs version 2.0.0 of [dotnetsay](https://www.nuget.org/packages/dotnetsay/) as a global tool.
 
+- **`dotnet tool install -g dotnetsay@2.1.7`**
+
+  Installs version 2.1.7 of [dotnetsay](https://www.nuget.org/packages/dotnetsay/) as a global tool.
+
 - **`dotnet tool install dotnetsay`**
 
   Installs [dotnetsay](https://www.nuget.org/packages/dotnetsay/) as a local tool for the current directory.
 
+- **`dotnet tool install dotnetsay@2.1.7`**
+
+  Installs version 2.1.7 of [dotnetsay](https://www.nuget.org/packages/dotnetsay/) as a local tool for the current directory.
+
 - **`dotnet tool install -g dotnetsay --verbosity minimal`**
 
   Installs [dotnetsay](https://www.nuget.org/packages/dotnetsay/) as a global tool with the verbosity of minimal. The default verbosity for global tool is quiet.
diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md
@@ -1,7 +1,7 @@
 ---
 title: dotnet tool update command
 description: The dotnet tool update command updates the specified .NET tool on your machine.
-ms.date: 10/28/2025
+ms.date: 11/12/2025
 ---
 # dotnet tool update
 
@@ -54,7 +54,11 @@ The `dotnet tool update` command provides a way for you to update .NET tools on
 
 - **`PACKAGE_ID`**
 
-  Name/ID of the NuGet package that contains the .NET global tool to update. You can find the package name using the [dotnet tool list](dotnet-tool-list.md) command.
+  Name/ID of the NuGet package that contains the .NET global tool to update.
+
+  Starting in .NET 10.0.100 SDK, use the name/ID, and version separated by `@` to update a .NET tool.
+
+  You can find the package name using the [dotnet tool list](dotnet-tool-list.md) command.
 
 ## Options
 
@@ -138,9 +142,13 @@ The `dotnet tool update` command provides a way for you to update .NET tools on
 
   Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) global tool to the latest patch version, with a major version of `2`, and a minor version of `0`.
 
-- **`dotnet tool update -g dotnetsay --version (2.0.*,2.1.4)`**
+- **`dotnet tool update -g dotnetsay@2.1.7*`**
+
+  Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) global tool to the latest patch version, 2.1.7.
+
+- **`dotnet tool update -g dotnetsay --version (2.0.0,2.1.7)`**
 
-  Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) global tool to the lowest version within the specified range `(> 2.0.0 && < 2.1.4)`, version `2.1.0` would be installed. For more information on semantic versioning ranges, see [NuGet packaging version ranges](/nuget/concepts/package-versioning#version-ranges).
+  Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) global tool to the lowest version within the specified range `(> 2.0.0 && < 2.1.7)`, version `2.1.0` would be installed. For more information on semantic versioning ranges, see [NuGet packaging version ranges](/nuget/concepts/package-versioning#version-ranges).
 
 ## See also
 
diff --git a/docs/core/tools/dotnet-workload-install.md b/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: 09/10/2021
+ms.date: 11/12/2025
 no-loc: [dotnet workload install]
 ---
 # dotnet workload install
@@ -96,7 +96,7 @@ The `dotnet workload update` command also downloads advertising manifests. The d
 
 [!INCLUDE [verbosity](../../../includes/cli-verbosity-packages.md)]
 
-[!INCLUDE [version](../../../includes/cli-version.md)]
+[!INCLUDE [workload-version](../../../includes/cli-workload-version.md)]
 
 ## Examples
 
@@ -111,3 +111,9 @@ The `dotnet workload update` command also downloads advertising manifests. The d
   ```dotnetcli
   dotnet workload install maui-android maui-ios
   ```
+
+- Install the workload version specified by the `@` character:
+
+  ```dotnetcli
+  dotnet workload install maui@10.0.100
+  ```
diff --git a/docs/core/tools/dotnet-workload-search.md b/docs/core/tools/dotnet-workload-search.md
@@ -1,7 +1,7 @@
 ---
 title: dotnet workload search command
 description: The 'dotnet workload search' command searches for optional workloads.
-ms.date: 08/31/2021
+ms.date: 11/12/2025
 ---
 # dotnet workload search
 
@@ -14,7 +14,7 @@ ms.date: 08/31/2021
 ## Synopsis
 
 ```dotnetcli
-dotnet workload search [<SEARCH_STRING>] [-v|--verbosity <LEVEL>]
+dotnet workload search [<SEARCH_STRING>] [-v|--verbosity <LEVEL>] [version <WORKLOAD_VERSION>]
 
 dotnet workload search -?|-h|--help
 ```
@@ -37,6 +37,8 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
 
 [!INCLUDE [verbosity](../../../includes/cli-verbosity-minimal.md)]
 
+[!INCLUDE [workload-version](../../../includes/cli-workload-version.md)]
+
 ## Examples
 
 - List all available workloads:
@@ -50,3 +52,9 @@ For more information about the `dotnet workload` commands, see the [dotnet workl
   ```dotnetcli
   dotnet workload search maui
   ```
+
+- Search for a workload that matches the provided version:
+
+  ```dotnetcli
+  dotnet workload search version maui@10.0.100
+  ```
diff --git a/includes/cli-workload-version.md b/includes/cli-workload-version.md
@@ -0,0 +1,7 @@
+---
+ms.date: 11/12/2025
+ms.topic: include
+---
+- **`version <WORKLOAD_VERSION>`**
+
+  A workload version to display, or one or more workloads and their versions joined by the `@` character. Support for the `@` character is available since 9.0.200 SDK.
