Document dotnet pack nuspec, --version, and file-based app support (.NET 10 SDK)

docs/core/tools/dotnet-pack.md

@@ -1,7 +1,8 @@
 ---
 title: dotnet pack command
 description: The dotnet pack command creates NuGet packages for your .NET project.
-ms.date: 09/29/2025
+ms.date: 04/02/2026
+ai-usage: ai-assisted
 ---
 # dotnet pack
 
@@ -14,13 +15,14 @@ ms.date: 09/29/2025
 ## Synopsis
 
 ```dotnetcli
-dotnet pack [<PROJECT>|<SOLUTION>]
-  [--artifacts-path <ARTIFACTS_DIR>] [-c|--configuration <CONFIGURATION>]
-  [--disable-build-servers] [--force] [--include-source] [--include-symbols]
-  [--interactive] [--no-build] [--no-dependencies] [--no-restore] [--nologo]
-  [-o|--output <OUTPUT_DIRECTORY>] [--runtime <RUNTIME_IDENTIFIER>]
-  [-s|--serviceable] [--tl:[auto|on|off]] [-v|--verbosity <LEVEL>]
-  [--version-suffix <VERSION_SUFFIX>]
+dotnet pack [<PROJECT>|<SOLUTION>|<NUSPEC>]
+    [--artifacts-path <ARTIFACTS_DIR>] [-c|--configuration <CONFIGURATION>]
+    [--disable-build-servers] [--force] [--include-source] [--include-symbols]
+    [--interactive] [--no-build] [--no-dependencies] [--no-restore] [--nologo]
+    [-o|--output <OUTPUT_DIRECTORY>] [-p|--property:<PROPERTYNAME>=<VALUE>]
+    [--runtime <RUNTIME_IDENTIFIER>]
+    [-s|--serviceable] [--tl:[auto|on|off]] [-v|--verbosity <LEVEL>]
+    [--version <VERSION>] [--version-suffix <VERSION_SUFFIX>]
 
 dotnet pack -h|--help
 ```
@@ -29,6 +31,8 @@ dotnet pack -h|--help
 
 The `dotnet pack` command builds the project and creates NuGet packages. The result of this command is a NuGet package (that is, a *.nupkg* file).
 
+Starting with .NET 10, you can also pass a *.nuspec* file directly as the argument. In this case, `dotnet pack` creates the package from the *.nuspec* file without requiring a project file and without running MSBuild.
+
 If you want to generate a package that contains the debug symbols, you have two options available:
 
 - `--include-symbols` - it creates the symbols package.
@@ -41,8 +45,6 @@ By default, `dotnet pack` builds the project first. If you wish to avoid this be
 > [!NOTE]
 > In some cases, the implicit build cannot be performed. This can occur when `GeneratePackageOnBuild` is set, to avoid a cyclic dependency between build and pack targets. The build can also fail if there is a locked file or other issue.
 
-You can provide MSBuild properties to the `dotnet pack` command for the packing process. For more information, see [NuGet pack target properties](/nuget/reference/msbuild-targets#pack-target) and the [MSBuild Command-Line Reference](/visualstudio/msbuild/msbuild-command-line-reference). The [Examples](#examples) section shows how to use the MSBuild `-p` switch for a couple of different scenarios.
-
 > [!NOTE]
 > Web projects aren't packable.
 
@@ -54,9 +56,9 @@ You can provide MSBuild properties to the `dotnet pack` command for the packing
 
 ## Arguments
 
-`PROJECT | SOLUTION`
+`PROJECT | SOLUTION | NUSPEC`
 
-  The project or solution to pack. It's either a path to a csproj, vbproj, or fsproj file, or to a solution file or directory. If not specified, the command searches the current directory for a project or solution file.
+  The project, solution, or *.nuspec* file to pack. It's either a path to a csproj, vbproj, or fsproj file, to a solution file or directory, or to a *.nuspec* file. If not specified, the command searches the current directory for a project or solution file.
 
 ## Options
 
@@ -104,6 +106,17 @@ You can provide MSBuild properties to the `dotnet pack` command for the packing
 
     In the 7.0.200 SDK, if you specify the `--output` option when running this command on a solution, the CLI will emit an error. This is a regression and was fixed in 7.0.201 and later versions of the .NET SDK.
 
+- **`-p|--property:<PROPERTYNAME>=<VALUE>`**
+
+  Sets one or more MSBuild properties. When packing a *.nuspec* file directly, the properties are used for token replacement in the *.nuspec* file rather than as MSBuild properties. Specify multiple properties delimited by semicolons or by repeating the option:
+
+  ```dotnetcli
+  --property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
+  --property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>
+  ```
+
+   For more information, see [NuGet pack target properties](/nuget/reference/msbuild-targets#pack-target) and [MSBuild command-line reference](/visualstudio/msbuild/msbuild-command-line-reference).
+
 - **`--runtime <RUNTIME_IDENTIFIER>`**
 
   Specifies the target runtime to restore packages for. For a list of Runtime Identifiers (RIDs), see the [RID catalog](../rid-catalog.md).
@@ -116,6 +129,13 @@ You can provide MSBuild properties to the `dotnet pack` command for the packing
 
 - [!INCLUDE [verbosity](includes/cli-verbosity.md)]
 
+- **`--version <VERSION>`**
+
+  The version of the package to create. When packing a *.nuspec* file, overrides the version number in the *.nuspec* file.
+
+  > [!NOTE]
+  > Available starting in .NET 10.
+
 - **`--version-suffix <VERSION_SUFFIX>`**
 
   Defines the value for the `VersionSuffix` MSBuild property. The effect of this property on the package version depends on the values of the `Version` and `VersionPrefix` properties, as shown in the following table:
@@ -184,7 +204,7 @@ You can provide MSBuild properties to the `dotnet pack` command for the packing
   dotnet pack --runtime win-x64
   ```
 
-- Pack the project using a *.nuspec* file:
+- Pack the project using a *.nuspec* file (MSBuild project-based approach):
 
   ```dotnetcli
   dotnet pack ~/projects/app1/project.csproj -p:NuspecFile=~/projects/app1/project.nuspec -p:NuspecBasePath=~/projects/app1/nuget
@@ -195,3 +215,21 @@ You can provide MSBuild properties to the `dotnet pack` command for the packing
   - [Packing using a .nuspec](/nuget/reference/msbuild-targets#packing-using-a-nuspec)
   - [Advanced extension points to create customized package](/nuget/reference/msbuild-targets#advanced-extension-points-to-create-customized-package)
   - [Global properties](/visualstudio/msbuild/msbuild-properties#global-properties)
+
+- Pack a *.nuspec* file directly, without a project file (.NET 10 SDK and later):
+
+  ```dotnetcli
+  dotnet pack MyPackage.nuspec --output ./artifacts
+  ```
+
+- Pack a *.nuspec* file directly and set the package version (.NET 10 SDK and later):
+
+  ```dotnetcli
+  dotnet pack MyPackage.nuspec --version 1.2.3 --output ./artifacts
+  ```
+
+- Pack a *.nuspec* file directly and use token replacement (.NET 10 SDK and later):
+
+  ```dotnetcli
+  dotnet pack MyPackage.nuspec --property Version=1.2.3 --property Configuration=Release --output ./artifacts
+  ```