From 7f4dda31b8a49bbd41768c2bde2a37084e13c838 Mon Sep 17 00:00:00 2001
From: Andy Zivkovic <Andy.Zivkovic@microsoft.com>
Date: Fri, 3 Oct 2025 14:54:48 +0930
Subject: [PATCH] Initial docs for dotnet package update

---
 docs/core/tools/dotnet-package-update.md | 117 +++++++++++++++++++++++
 docs/core/tools/index.md                 |   2 +-
 docs/navigate/tools-diagnostics/toc.yml  |   2 +
 3 files changed, 120 insertions(+), 1 deletion(-)
 create mode 100644 docs/core/tools/dotnet-package-update.md

diff --git a/docs/core/tools/dotnet-package-update.md b/docs/core/tools/dotnet-package-update.md
new file mode 100644
index 0000000000000..53007081f211d
--- /dev/null
+++ b/docs/core/tools/dotnet-package-update.md
@@ -0,0 +1,117 @@
+---
+title: dotnet package update command
+description: Update PackageReferences in a project.
+author: zivkan
+ms.date: 10/03/2025
+---
+# dotnet package update
+
+**This article applies to:** ✔️ .NET 10 SDK and later versions
+
+## Name
+
+`dotnet package update` - Update referenced packages in a project.
+
+## Synopsis
+
+```dotnetcli
+dotnet package update [<packages>...]
+    [--interactive] [--project <path>]
+    [--verbosity <level>] [--vulnerable]
+
+dotnet package update -h|--help
+```
+
+## Description
+
+The `dotnet package update` command updates packages used by projects.
+If [NuGetAudit](/nuget/concepts/auditing-packages) is enabled, it can also attempt to automatically update update packages with known vulnerabilities to fixed versions.
+
+### Warnings as Errors
+
+`dotnet package update` does implicit restores to check if the resulting package graph is free of errors.
+Using `--vulnerable` also does an implicit restore to find NuGetAudit warnings.
+However, if your project uses `WarningsAsErrors` or `TreatWarningsAsErrors`, NuGet's restore warnings can cause restore to fail, preventing the update from completing.
+
+We recommend taking advantage of MSBuild conditions and environment variables as a workaround until [this feature request](https://github.com/NuGet/Home/issues/14311) is implemented.
+For example, set `<TreatWarningsAsErrors Condition=" '$(CustomCondition)' == ''>true</TreatWarningsAsErrors>` in your project, and then on most Linux and Mac shells you can run `CustomCondition=true dotnet package update`.
+On Windows Command Prompt and PowerShell, you will need to set the environment variable, run dotnet package update, then unset the environment variable as three separate commands.
+
+## Arguments
+
+- **`packages`**
+
+  An optional list of packages to update.
+  When no packages are provided, the command will attempt to update all packages referenced by the project.
+  Packages can be a package name optionally followed by an `@` and a version number.
+  For example, `dotnet package update Contoso.Utilities` or `dotnet package update Contoso.Utilities@3.2.1`.
+  When no version is provided, it will find the highest version available on the configured package sources.
+
+## Options
+
+- **`--interactive`**
+
+    Allows the command to stop and wait for user input or action (for example to complete authentication).
+
+- **`--project <path>`**
+
+    The project which packages should be updated in.
+    If a directory is provided, it searches for project and solution files in the directory.
+    Defaults to the current working directory.
+
+- **`--verbosity`**
+
+    Display this amount of details in the output: `[n]ormal`, `[m]inimal`, `[q]uiet`, `[d]etailed`, or `[diag]nostic`. The default is `normal`.
+
+- **`--vulnerable`**
+
+    If restore reports any packages as having known vulnerabilities, this command will upgrade those packages.
+    Using this option will upgrade packages to the lowest version that is higher than the currently referenced version, that does not have any known vulnerabilities.
+
+[!INCLUDE [help](../../../includes/cli-help.md)]
+
+## Examples
+
+- Update all packages in the project to the highest version available
+
+    ```dotnetcli
+    dotnet package update
+    ```
+
+    ```output
+    Updating outdated packages in S:\src\test\update\ConsoleApp1.
+      ConsoleApp1:
+        Updated Microsoft.Extensions.Configuration 9.0.0 to 9.0.9.
+        Updated Microsoft.Extensions.DependencyInjection 9.0.0 to 9.0.9.
+
+    Updated 2 packages in 7 scanned packages.
+    ```
+
+- Update Contoso.Utilities to the highest version available, and Fabrikam.WebApi to version 1.2.3
+
+    ```dotnetcli
+    dotnet package update Contoso.Utilities Fabrikam.WebApi@1.2.3
+    ```
+
+    ```output
+    Updating outdated packages in S:\src\test\update\ConsoleApp1.
+      ConsoleApp1:
+        Updated Contoso.Utilities 2.3.1 to 2.4.6.
+        Updated Fabrikam.WebApi 1.0.2 to 1.2.3.
+
+    Updated 2 packages in 2 scanned packages.
+    ```
+
+- Update packages with known vulnerabilities
+
+    ```dotnetcli
+    dotnet package update --vulnerable
+    ```
+
+    ```output
+    Updating packages with security advisories in S:\src\test\update\ConsoleApp1
+      ConsoleApp1:
+        Updating System.Text.Json 8.0.0 to 8.0.5.
+
+    Updated 1 packages in 31 scanned packages.
+    ```
diff --git a/docs/core/tools/index.md b/docs/core/tools/index.md
index 33c8da824c4bc..8fdb78674e83e 100644
--- a/docs/core/tools/index.md
+++ b/docs/core/tools/index.md
@@ -78,6 +78,7 @@ The following commands are installed by default:
 - [`package list`](dotnet-package-list.md)
 - [`package remove`](dotnet-package-remove.md)
 - [`package search`](dotnet-package-search.md)
+- [`package update`](dotnet-package-update.md)
 - [`reference add`](dotnet-reference-add.md)
 - [`reference list`](dotnet-reference-list.md)
 - [`reference remove`](dotnet-reference-remove.md)
@@ -96,7 +97,6 @@ The following commands are installed by default:
 - [`nuget verify`](dotnet-nuget-verify.md) (Available since .NET 5 SDK)
 - [`nuget trust`](dotnet-nuget-trust.md) (Available since .NET 5 SDK)
 - [`nuget sign`](dotnet-nuget-sign.md) (Available since .NET 6 SDK)
-- [`package search`](dotnet-package-search.md) (Available since .NET 8.0.2xx SDK)
 - [`nuget why`](dotnet-nuget-why.md) (Available since .NET 8.0.4xx SDK)
 
 ### Workload management commands
diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml
index 57d0df4e2781b..918491470aebb 100644
--- a/docs/navigate/tools-diagnostics/toc.yml
+++ b/docs/navigate/tools-diagnostics/toc.yml
@@ -190,6 +190,8 @@ items:
                 href: ../../core/tools/dotnet-package-remove.md
               - name: dotnet package search
                 href: ../../core/tools/dotnet-package-search.md
+              - name: dotnet package update
+                href: ../../core/tools/dotnet-package-update.md
           - name: dotnet publish
             href: ../../core/tools/dotnet-publish.md
           - name: dotnet reference add/list/remove