Merge pull request #3487 from NuGet/main

Docs to Live, Mid October

Author: nkolev92

.github/copilot-instructions.md

@@ -0,0 +1,56 @@
+# .NET Documentation Guidelines
+
+## Disclosure
+
+For any Markdown files generated by AI, always disclose that they were created with the assistance of AI. Add the following frontmatter key/value pair:
+
+```markdown
+ai-usage: ai-generated
+```
+
+## Terminology
+
+Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
+
+## Writing Style
+
+Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics:
+
+### Voice and Tone
+
+- Active voice, second person addressing reader directly.
+- Conversational tone with contractions.
+- Present tense for instructions/descriptions.
+- Imperative mood for instructions ("Call the method" not "You should call the method").
+- Use "might" instead of "may" for possibility.
+- Use "can" instead of "may" for permissible actions.
+- Avoid "we"/"our" referring to documentation authors or product teams.
+
+### Structure and Format
+
+- Sentence case headings (no gerunds in titles).
+- Be concise, break up long sentences.
+- Oxford comma in lists.
+- Use bullets for unordered lists.
+- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.)
+- Ordered and unordered lists should use complete sentences with proper punctuation, ending with a period if it's more than three words.
+- Avoid "etc." or "and so on" - provide complete lists or use "for example".
+- Use "for example" instead of "e.g.".
+- Use "that is" instead of "i.e.".
+- No consecutive headings without content between them.
+
+### Formatting Conventions
+
+- **Bold** for UI elements.
+- `Code style` for file names, folders, custom types, non-localizable text.
+- Raw URLs in angle brackets.
+- Use relative links for files in this repo.
+- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links.
+
+## File Naming
+
+New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.).
+
+## Special Cases
+
+- When you (Copilot) are assigned an issue in GitHub, after you've completed your work and the workflows (status checks) have run, check to make sure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced.

docs/TOC.md

@@ -17,6 +17,7 @@
 ### [nuget.exe CLI](consume-packages/install-use-packages-nuget-cli.md)
 ### [Package Manager Console (PowerShell)](consume-packages/install-use-packages-powershell.md)
 ## Configure NuGet
+### [Visual Studio options](consume-packages/nuget-visual-studio-options.md)
 ### Package restore options
 #### [Restore packages](consume-packages/package-restore.md)
 #### [Troubleshooting](consume-packages/package-restore-troubleshooting.md)

docs/archive/project-json-and-uwp.md

@@ -12,6 +12,8 @@ ms.topic: conceptual
 > [!Important]
 > This content is deprecated. Projects should use the PackageReference formats.
 > Learn how to [migrate your project.json project to PackageReference](./project-json.md#migrate-projectjson-to-packagereference).
+> Visual Studio 2026 automatically migrates project.json at solution load time.
+> [.NET 10 SDK & NuGet.exe 7.0](../release-notes/NuGet-7.0.md) do not support project.json projects.
 
 This document describes the package structure that employs features in NuGet 3+ (Visual Studio 2015 and later). The `minClientVersion` property of your `.nuspec` can be used to state that you require the features described here by setting it to 3.1.
 

docs/archive/project-json-impact.md

@@ -12,6 +12,8 @@ ms.topic: conceptual
 > [!Important]
 > This content is deprecated. Projects should use the PackageReference formats.
 > Learn how to [migrate your project.json project to PackageReference](./project-json.md#migrate-projectjson-to-packagereference).
+> Visual Studio 2026 automatically migrates project.json at solution load time.
+> [.NET 10 SDK & NuGet.exe 7.0](../release-notes/NuGet-7.0.md) do not support project.json projects.
 
 The `project.json` system used in NuGet 3+ affects package authors in several ways as described in the following sections.
 

docs/archive/project-json.md

@@ -12,6 +12,8 @@ ms.topic: reference
 > [!Important]
 > This content is deprecated. Projects should use the PackageReference formats.
 > Learn how to [migrate your project.json project to PackageReference](#migrate-projectjson-to-packagereference).
+> Visual Studio 2026 automatically migrates project.json at solution load time.
+> [.NET 10 SDK & NuGet.exe 7.0](../release-notes/NuGet-7.0.md) do not support project.json projects.
 
 *NuGet 3.x*
 
@@ -40,15 +42,35 @@ The [`project.lock.json`](#projectlockjson) file (described below) is also used
 
 ## Migrate project.json to PackageReference
 
-The migration between project.json and PackageReference is straightforward. The easiest way to do it to use the built-in migrator in the latest Visual Studio 2022, Update 14.
+The migration between project.json and PackageReference is straightforward.
+
+### Automatic migration in Visual Studio 2026
+
+Visual Studio 2026 and later automatically migrates project.json projects to PackageReference when you open a solution containing project.json projects.
+The migration happens at solution load time:
+
+1. Open a solution containing project.json projects in Visual Studio 2026 or later.
+1. Visual Studio automatically detects project.json files and migrates them to PackageReference format.
+1. To check migration status, open the [Output Window](/visualstudio/ide/output-window) and select Show output from "Package Manager".
+You should see messages like "Migrating project.json project..." followed by "Migration Succeeded" for each project.
+Any errors will appear in the Error List.
+1. A backup of the original project file and project.json file is created in a `Backup` folder in the root of the project directory.
+1. The migration converts all package dependencies to PackageReference format in the project file.
+
+
+### Manual migration in Visual Studio 2022
+
+For Visual Studio 2022 and earlier, you can use the built-in migrator:
 
 1. Load the project.json project in Visual Studio.
 1. Go to the solution explorer of the project.json project and find the dependencies node.
-1. Click `Migrate project.json to PackageReference...`!
+1. Right-click and select `Migrate project.json to PackageReference...`
 
 ![Migrating from project.json to PackageReference](media/project-json-migrator.png)
 
-Alternatively, you may use the [dotnet migrate](/dotnet/core/tools/dotnet-migrate), or do the migration manually by taking all of the content from the project.json file and replacing it with the equivalent [PackageReference syntax](../consume-packages/Package-References-in-Project-Files.md).
+### Alternative migration methods
+
+Alternatively, you may use the [dotnet migrate](/dotnet/core/tools/dotnet-migrate) command-line tool, or do the migration manually by taking all of the content from the project.json file and replacing it with the equivalent [PackageReference syntax](../consume-packages/Package-References-in-Project-Files.md).
 
 ## Dependencies
 

docs/concepts/Auditing-Packages.md

@@ -4,7 +4,7 @@ description: How to audit package dependencies for security vulnerabilities and
 author: JonDouglas
 ms.author: jodou
 ms.topic: conceptual
-ms.date: 05/05/2025
+ms.date: 10/01/2025
 ---
 
 # Auditing package dependencies for security vulnerabilities
@@ -27,6 +27,7 @@ We also have a [blog post](https://devblogs.microsoft.com/nuget/nugetaudit-2-0-e
 | [6.10](../release-notes/NuGet-6.10.md) | N/A | Visual Studio 2022 17.10 | [NuGetAudit](#running-a-security-audit-with-restore) for packages.config|
 | [6.11](../release-notes/NuGet-6.11.md) | .NET 8 SDK (8.0.400) | Visual Studio 2022 17.11 | [NuGetAuditSuppress](#excluding-advisories) for PackageReference |
 | [6.12](../release-notes/NuGet-6.12.md) | .NET 9 SDK (9.0.100) | Visual Studio 2022 17.12 | [Audit sources](#audit-sources). [NuGetAuditSuppress](#excluding-advisories) for packages.config. |
+| [7.0](../release-notes/NuGet-7.0.md) | .NET 10 SDK (10.0.100) | Visual Studio 2026 | [NuGetAuditMode default changes for .NET 10](#configuring-nuget-audit). [`dotnet package update --vulnerable`](#security-vulnerabilities-found-with-updates) |
 
 ## Running a security audit with `restore`
 
@@ -157,7 +158,8 @@ If security vulnerabilities are found and updates are available for the package,
 
 - Edit the `.csproj` or other package version location (`Directory.Packages.props`) with a newer version containing a security fix.
 - Use the NuGet package manager user interface in Visual Studio to update the individual package.
-- Run the `dotnet add package` command with the respective package ID to update to the latest version.
+- Run the `dotnet package update --vulnerable` command to update all vulnerable packages in a project to the first version without known vulnerabilities.
+- Run the `dotnet package update` or `dotnet package add` commands with the respective package ID to update to the latest version. Use [`dotnet add package` when using .NET 9 or earlier](/dotnet/core/whats-new/dotnet-10/sdk#more-consistent-command-order).
 
 #### Transitive Packages
 

docs/consume-packages/Package-References-in-Project-Files.md

@@ -366,6 +366,14 @@ You can also set this conditional MSBuild property in your project file:
 
 If locked mode is `true`, restore will either restore the exact packages as listed in the lock file or fail if you updated the defined package dependencies for the project after lock file was created.
 
+#### Lock files and PrunePackageReference
+
+[PrunePackageReference](#prunepackagereference) changes the dependencies of a project, by removing unnecessary transitive packages.
+While removing these packages should not have an impact at runtime, it will affect lock files.
+If you enable pruning for an existing project, whenever the lock file gets regenerated, it may lead to fewer packages than before pruning.
+The lock file up to date check that powers locked mode is pruning aware, which means if you enabled pruning on a project, the check will account for packages that are pruned.
+However the next time the lock file is regenerated, it will exclude the pruned packages, so you may see a diff that's larger than usual.
+
 ### Make lock file part of your source repository
 
 If you are building an application, an executable, and the project in question is at the start of the dependency chain, then do check in the lock file to the source code repository so that NuGet can make use of it during restore.

docs/consume-packages/Package-Restore.md

@@ -44,6 +44,7 @@ If the package references in your project file or your *packages.config* file ar
 If you have missing packages or package-related errors after you run Package Restore, such as error icons in Solution Explorer, follow the instructions in [Troubleshooting Package Restore errors](package-restore-troubleshooting.md), or [reinstall or update](../consume-packages/reinstalling-and-updating-packages.md) the packages. In Visual Studio, the Package Manager Console provides several options for reinstalling packages. For more information, see [Use Package-Update](reinstalling-and-updating-packages.md#update-package-command).
 
 <a name="restore-using-visual-studio"></a>
+
 ## Restore packages in Visual Studio
 
 In Visual Studio on Windows, you can restore packages automatically or manually. First, configure Package Restore through **Tools** > **Options** > **NuGet Package Manager**.
@@ -52,9 +53,10 @@ In Visual Studio on Windows, you can restore packages automatically or manually.
 
 Configure the following Package Restore options at **Tools** > **Options** > **NuGet Package Manager** > **General**.
 
-![Screenshot that shows the NuGet Package Manager options.](media/Restore-01-AutoRestoreOptions.png)
+![Screenshot that shows the NuGet Package Manager options.](media/vsoptions/general.png)
 
 <a name="enable-and-disable-package-restore-in-visual-studio"></a>
+
 #### Allow NuGet to download missing packages
 
 Select **Allow NuGet to download missing packages** to enable package restore and the **Restore NuGet Packages** command. This selection sets the `packageRestore/enabled` setting to `True` in the [packageRestore section](../reference/nuget-config-file.md#packagerestore-section) of the global *NuGet.Config* file, at *%AppData%\\Roaming\\NuGet* on Windows or *~/.nuget/NuGet/* on Mac or Linux.
@@ -90,17 +92,20 @@ Select **Automatically check for missing packages during build in Visual Studio*
 You must select **Allow NuGet to download missing packages** as well as **Automatically check for missing packages during build in Visual Studio** in **Options** to enable package restore during build.
 
 <a name="choose-default-package-management-format"></a>
+
 #### Choose the default package management format
 
 NuGet has two package management formats, [PackageReference](Package-References-in-Project-Files.md) and [packages.config](../reference/packages-config.md). Select the format you want to use from the dropdown list under **Package Management**. You can also select whether to allow format selection on first package install.
 
 > [!Note]
+>
 > - If a project doesn't support both package management formats, NuGet uses the package management format that's compatible with the project, which might not be the default you set in the options. NuGet then won't prompt for selection on first install, even if you selected that option.
 >
 > - If you use Package Manager Console to install the first package in a project, NuGet doesn't prompt for format selection, even if that option is selected in **Options**.
 
 <a name="restore-packages-automatically-using-visual-studio"></a>
 <a name="restore-packages-manually-using-visual-studio"></a>
+
 ### Restore packages manually or automatically
 
 After you enable package restore in **Options**, you can right-click the solution in **Solution Explorer** and select **Restore NuGet Packages** to restore packages anytime.
@@ -112,6 +117,7 @@ For projects that use `<PackageReference>`, you can see the package references i
 If you see the error **This project references NuGet package(s) that are missing on this computer**, or **One or more NuGet packages need to be restored but couldn't be because consent has not been granted**, make sure you enabled automatic restore. For older projects, see [Migrate to automatic package restore](#migrate-to-automatic-package-restore-visual-studio). Also see [Troubleshooting package restore errors](Package-restore-troubleshooting.md).
 
 <a name="restore-using-the-dotnet-cli"></a>
+
 ## Restore by using the dotnet CLI
 
 [!INCLUDE [restore-dotnet-cli](includes/restore-dotnet-cli.md)]
@@ -120,11 +126,13 @@ If you see the error **This project references NuGet package(s) that are missing
 > To add a missing package reference to the project file, use [dotnet add package](/dotnet/core/tools/dotnet-add-package), which also runs `restore`.
 
 <a name="restore-using-the-nugetexe-cli"></a>
+
 ## Restore by using the NuGet CLI
 
 [!INCLUDE [restore-nuget-exe-cli](includes/restore-nuget-exe-cli.md)]
 
 <a name="restore-using-msbuild"></a>
+
 ## Restore by using MSBuild
 
 You can use [msbuild -t:restore](../reference/msbuild-targets.md#restore-target) to restore packages in NuGet 4.x+ and MSBuild 15.1+, which are included with Visual Studio 2017 and higher.
@@ -144,6 +152,7 @@ To use MSBuild restore:
 
 <a name="restore-using-azure-pipelines"></a>
 <a name="restore-using-azure-devops-server"></a>
+
 ## Restore with Azure Pipelines or Azure DevOps Server
 
 When you create a build definition in Azure Pipelines, you can include the [NuGet CLI restore](/azure/devops/pipelines/tasks/package/nuget#restore-nuget-packages) or [dotnet CLI restore](/azure/devops/pipelines/tasks/build/dotnet-core-cli) task in the definition before any build tasks. Some build templates include the restore task by default.
@@ -192,6 +201,7 @@ To avoid using packages in the HTTP cache:
 - For `nuget restore`, use the `-NoHttpCache` option, or for `dotnet restore`, use the `--no-http-cache` option. These options don't affect restore operations through the Visual Studio Package Manager or Console.
 
 <a name="migrate-to-automatic-package-restore-visual-studio"></a>
+
 ## Migrate to automatic package restore
 
 Earlier versions of NuGet supported an MSBuild-integrated package restore. Projects that use the deprecated MSBuild-integrated package restore should migrate to automatic package restore.