Update file-based app functionality in command reference (#48738)

meaghanlewis · web-flow · commit af508fd30fb2 · 2025-09-25T16:09:40.000-07:00
* add file based changes for dotnet build

* add file based command for dotnet clean

* add file-based app options for dotnet-run

* add file-based app details for dotnet publish

* add file-based app info for dotnet-restore

* Fix indentation

* add in file command

* make consistency edits across commands

* Specify the version file-based programs are available in.

* apply changes from review feedback

* move project-solution-file arguments to an include file

* add trailing newline to include

* specify behavior of dotnet run for arguments and using file option

* Add trailing newline at end of file
diff --git a/docs/core/tools/dotnet-build.md b/docs/core/tools/dotnet-build.md
@@ -1,20 +1,20 @@
 ---
 title: dotnet build command
 description: The dotnet build command builds a project and all of its dependencies.
-ms.date: 11/27/2023
+ms.date: 09/24/2025
 ---
 # dotnet build
 
-**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
+**This article applies to:** ✔️ .NET 6 and later versions
 
 ## Name
 
-`dotnet build` - Builds a project and all of its dependencies.
+`dotnet build` - Builds a project, solution, or file-based app and all of its dependencies.
 
 ## Synopsis
 
 ```dotnetcli
-dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
+dotnet build [<PROJECT>|<SOLUTION>|<FILE>] [-a|--arch <ARCHITECTURE>]
     [--artifacts-path <ARTIFACTS_DIR>]
     [-c|--configuration <CONFIGURATION>] [-f|--framework <FRAMEWORK>]
     [--disable-build-servers]
@@ -23,7 +23,7 @@ dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
     [-o|--output <OUTPUT_DIRECTORY>]
     [-p|--property:<PROPERTYNAME>=<VALUE>]
     [-r|--runtime <RUNTIME_IDENTIFIER>]
-    [--self-contained [true|false]] [--source <SOURCE>]
+    [-sc|--self-contained [true|false]] [--source <SOURCE>]
     [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
     [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]
 
@@ -32,16 +32,14 @@ dotnet build -h|--help
 
 ## Description
 
-The `dotnet build` command builds the project and its dependencies into a set of binaries. The binaries include the project's code in Intermediate Language (IL) files with a *.dll* extension.  Depending on the project type and settings, other files may be included, such as:
+The `dotnet build` command builds the project, solution, or file-based app and its dependencies into a set of binaries. The binaries include the project's code in Intermediate Language (IL) files with a *.dll* extension. Depending on the project type and settings, other files may be included, such as:
 
-- An executable that can be used to run the application, if the project type is an executable targeting .NET Core 3.0 or later.
+- An executable that can be used to run the application.
 - Symbol files used for debugging with a *.pdb* extension.
 - A *.deps.json* file, which lists the dependencies of the application or library.
 - A *.runtimeconfig.json* file, which specifies the shared runtime and its version for an application.
 - Other libraries that the project depends on (via project references or NuGet package references).
 
-For executable projects targeting versions earlier than .NET Core 3.0, library dependencies from NuGet are typically NOT copied to the output folder.  They're resolved from the NuGet global packages folder at run time. With that in mind, the product of `dotnet build` isn't ready to be transferred to another machine to run. To create a version of the application that can be deployed, you need to publish it (for example, with the [dotnet publish](dotnet-publish.md) command). For more information, see [.NET Application Deployment](../deploying/index.md).
-
 For executable projects targeting .NET Core 3.0 and later, library dependencies are copied to the output folder. This means that if there isn't any other publish-specific logic (such as Web projects have), the build output should be deployable.
 
 ### Implicit restore
@@ -64,7 +62,7 @@ To produce a library, omit the `<OutputType>` property or change its value to `L
 
 ### MSBuild
 
-`dotnet build` uses MSBuild to build the project, so it supports both parallel and incremental builds. For more information, see [Incremental Builds](/visualstudio/msbuild/incremental-builds).
+`dotnet build` uses MSBuild to build the project, solution, or file-based app. It supports both parallel and incremental builds. For more information, see [Incremental Builds](/visualstudio/msbuild/incremental-builds).
 
 In addition to its options, the `dotnet build` command accepts MSBuild options, such as `-p` for setting properties or `-l` to define a logger. For more information about these options, see the [MSBuild Command-Line Reference](/visualstudio/msbuild/msbuild-command-line-reference). Or you can also use the [dotnet msbuild](dotnet-msbuild.md) command.
 
@@ -77,9 +75,7 @@ Running `dotnet build` is equivalent to running `dotnet msbuild -restore`; howev
 
 ## Arguments
 
-`PROJECT | SOLUTION`
-
-The project or solution file to build. If a project or solution file isn't specified, MSBuild searches the current working directory for a file that has a file extension that ends in either *proj* or *sln* and uses that file.
+[!INCLUDE [arguments-project-solution-file](../../../includes/cli-arguments-project-solution-file.md)]
 
 ## Options
 
@@ -176,6 +172,14 @@ The project or solution file to build. If a project or solution file isn't speci
   dotnet build
   ```
 
+- Build a file-based app:
+
+  ```dotnetcli
+  dotnet build MyProject.cs
+  ```
+
+  File-based app support was added in .NET SDK 10.0.100.
+
 - Build a project and its dependencies using Release configuration:
 
   ```dotnetcli
diff --git a/docs/core/tools/dotnet-clean.md b/docs/core/tools/dotnet-clean.md
@@ -1,11 +1,11 @@
 ---
 title: dotnet clean command
 description: The dotnet clean command cleans the current directory.
-ms.date: 02/14/2020
+ms.date: 09/24/2025
 ---
 # dotnet clean
 
-**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
+**This article applies to:** ✔️ .NET 6 and later versions
 
 ## Name
 
@@ -14,7 +14,7 @@ ms.date: 02/14/2020
 ## Synopsis
 
 ```dotnetcli
-dotnet clean [<PROJECT>|<SOLUTION>] [--artifacts-path <ARTIFACTS_DIR>]
+dotnet clean [<PROJECT>|<SOLUTION>|<FILE>] [--artifacts-path <ARTIFACTS_DIR>]
     [-c|--configuration <CONFIGURATION>]
     [-f|--framework <FRAMEWORK>] [--interactive]
     [--nologo] [-o|--output <OUTPUT_DIRECTORY>]
@@ -30,37 +30,35 @@ The `dotnet clean` command cleans the output of the previous build. It's impleme
 
 ## Arguments
 
-`PROJECT | SOLUTION`
-
-The MSBuild project or solution to clean. If a project or solution file is not specified, MSBuild searches the current working directory for a file that has a file extension that ends in *proj* or *sln*, and uses that file.
+[!INCLUDE [arguments-project-solution-file](../../../includes/cli-arguments-project-solution-file.md)]
 
 ## Options
 
 [!INCLUDE [artifacts-path](../../../includes/cli-artifacts-path.md)]
 
 [!INCLUDE [configuration](../../../includes/cli-configuration-clean.md)]
 
-* **`-f|--framework <FRAMEWORK>`**
+- **`-f|--framework <FRAMEWORK>`**
 
   The [framework](../../standard/frameworks.md) that was specified at build time. The framework must be defined in the [project file](../project-sdk/overview.md). If you specified the framework at build time, you must specify the framework when cleaning.
 
 [!INCLUDE [help](../../../includes/cli-help.md)]
 
 [!INCLUDE [interactive](../../../includes/cli-interactive-3-0.md)]
 
-* **`--nologo`**
+- **`--nologo`**
 
   Doesn't display the startup banner or the copyright message.
 
-* **`-o|--output <OUTPUT_DIRECTORY>`**
+- **`-o|--output <OUTPUT_DIRECTORY>`**
 
   The directory that contains the build artifacts to clean. Specify the `-f|--framework <FRAMEWORK>` switch with the output directory switch if you specified the framework when the project was built.
 
   - .NET 7.0.200 SDK and later
 
     If you specify the `--output` option when running this command on a solution, the CLI will emit a warning (an error in 7.0.200) due to the unclear semantics of the output path. The `--output` option is disallowed because all outputs of all built projects would be copied into the specified directory, which isn't compatible with multi-targeted projects, as well as projects that have different versions of direct and transitive dependencies. For more information, see [Solution-level `--output` option no longer valid for build-related commands](../compatibility/sdk/7.0/solution-level-output-no-longer-valid.md).
 
-* **`-r|--runtime <RUNTIME_IDENTIFIER>`**
+- **`-r|--runtime <RUNTIME_IDENTIFIER>`**
 
   Cleans the output folder of the specified runtime. This is used when a [self-contained deployment](../deploying/index.md#self-contained-deployment) was created.
 
@@ -70,13 +68,21 @@ The MSBuild project or solution to clean. If a project or solution file is not s
 
 ## Examples
 
-* Clean a default build of the project:
+- Clean a default build of the project:
 
   ```dotnetcli
   dotnet clean
   ```
 
-* Clean a project built using the Release configuration:
+- Clean a file-based program:
+
+  ```dotnetcli
+  dotnet clean Program.cs.
+  ```
+
+  File-based app support was added in .NET SDK 10.0.100.
+
+- Clean a project built using the Release configuration:
 
   ```dotnetcli
   dotnet clean --configuration Release
diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md
@@ -1,11 +1,11 @@
 ---
 title: dotnet publish command
 description: The dotnet publish command publishes a .NET project or solution to a directory.
-ms.date: 01/07/2025
+ms.date: 09/24/2025
 ---
 # dotnet publish
 
-**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
+**This article applies to:** ✔️ .NET 6 and later versions
 
 ## Name
 
@@ -14,7 +14,7 @@ ms.date: 01/07/2025
 ## Synopsis
 
 ```dotnetcli
-dotnet publish [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
+dotnet publish [<PROJECT>|<SOLUTION>|<FILE>] [-a|--arch <ARCHITECTURE>]
     [--artifacts-path <ARTIFACTS_DIR>]
     [-c|--configuration <CONFIGURATION>] [--disable-build-servers]
     [-f|--framework <FRAMEWORK>] [--force] [--interactive]
@@ -114,13 +114,7 @@ For more information, see the following resources:
 
 ## Arguments
 
-- **`PROJECT|SOLUTION`**
-
-  The project or solution to publish.
-
-  * `PROJECT` is the path and filename of a C#, F#, or Visual Basic project file, or the path to a directory that contains a C#, F#, or Visual Basic project file. If the directory is not specified, it defaults to the current directory.
-
-  * `SOLUTION` is the path and filename of a solution file (*.sln* or *.slnx* extension), or the path to a directory that contains a solution file. If the directory is not specified, it defaults to the current directory.
+[!INCLUDE [arguments-project-solution-file](../../../includes/cli-arguments-project-solution-file.md)]
 
 ## Options
 
@@ -186,12 +180,6 @@ For more information, see the following resources:
 
     If you specify a relative path when publishing a solution, all output for all projects goes into the specified folder relative to the current working directory. To make publish output go to separate folders for each project, specify a relative path by using the msbuild `PublishDir` property instead of the `--output` option. For example, `dotnet publish -p:PublishDir=.\publish` sends publish output for each project to a `publish` folder under the folder that contains the project file.
 
-  - .NET Core 2.x SDK
-
-    If you specify a relative path when publishing a project, the generated output directory is relative to the project file location, not to the current working directory.
-
-    If you specify a relative path when publishing a solution, each project's output goes into a separate folder relative to the project file location. If you specify an absolute path when publishing a solution, all publish output for all projects goes into the specified folder.
-
 [!INCLUDE [os](../../../includes/cli-os.md)]
 
 - **`--sc|--self-contained [true|false]`**
@@ -268,6 +256,14 @@ For more information, see the following resources:
   dotnet publish --no-dependencies
   ```
 
+- Publish the file-based C# program *app.cs* in the current directory:
+
+  ```dotnetcli
+  dotnet publish app.cs
+  ```
+
+  File-based program support was added in .NET SDK 10.0.100.
+
 ## See also
 
 - [.NET application publishing overview](../deploying/index.md)
diff --git a/docs/core/tools/dotnet-restore.md b/docs/core/tools/dotnet-restore.md
@@ -1,11 +1,11 @@
 ---
 title: dotnet restore command
 description: Learn how to restore dependencies and project-specific tools with the dotnet restore command.
-ms.date: 07/19/2023
+ms.date: 09/24/2025
 ---
 # dotnet restore
 
-**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
+**This article applies to:** ✔️ .NET 6 and later versions
 
 ## Name
 
@@ -14,7 +14,7 @@ ms.date: 07/19/2023
 ## Synopsis
 
 ```dotnetcli
-dotnet restore [<ROOT>] [--configfile <FILE>] [--disable-build-servers]
+dotnet restore [<PROJECT>|<SOLUTION>|<FILE>] [--configfile <FILE>] [--disable-build-servers]
     [--disable-parallel]
     [-f|--force] [--force-evaluate] [--ignore-failed-sources]
     [--interactive] [--lock-file-path <LOCK_FILE_PATH>] [--locked-mode]
@@ -86,9 +86,7 @@ There are three specific settings that `dotnet restore` ignores:
 
 ## Arguments
 
-- **`ROOT`**
-
-  Optional path to the project file to restore.
+[!INCLUDE [arguments-project-solution-file](../../../includes/cli-arguments-project-solution-file.md)]
 
 ## Options
 
@@ -184,19 +182,19 @@ There are three specific settings that `dotnet restore` ignores:
   dotnet restore ./projects/app1/app1.csproj
   ```
 
-- Restore the dependencies and tools for the project in the current   directory using the file path provided as the source:
+- Restore the dependencies and tools for the project in the current directory using the file path provided as the source:
 
   ```dotnetcli
   dotnet restore -s c:\packages\mypackages
   ```
 
-- Restore the dependencies and tools for the project in the current   directory using the two file paths provided as sources:
+- Restore the dependencies and tools for the project in the current directory using the two file paths provided as sources:
 
   ```dotnetcli
   dotnet restore -s c:\packages\mypackages -s c:\packages\myotherpackages
   ```
 
-- Restore dependencies and tools for the project in the current directory   showing detailed output:
+- Restore dependencies and tools for the project in the current directory showing detailed output:
 
   ```dotnetcli
   dotnet restore --verbosity detailed
diff --git a/docs/core/tools/dotnet-run.md b/docs/core/tools/dotnet-run.md
@@ -1,11 +1,11 @@
 ---
 title: dotnet run command
 description: The dotnet run command provides a convenient option to run your application from the source code.
-ms.date: 03/26/2025
+ms.date: 09/24/2025
 ---
 # dotnet run
 
-**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
+**This article applies to:** ✔️ .NET 6 and later versions
 
 ## Name
 
@@ -14,8 +14,8 @@ ms.date: 03/26/2025
 ## Synopsis
 
 ```dotnetcli
-dotnet run [-a|--arch <ARCHITECTURE>] [-c|--configuration <CONFIGURATION>]
-    [-e|--environment <KEY=VALUE>]
+dotnet run [<applicationArguments>] [-a|--arch <ARCHITECTURE>] [-c|--configuration <CONFIGURATION>]
+    [-e|--environment <KEY=VALUE>] [--file <FILE_PATH>]
     [-f|--framework <FRAMEWORK>] [--force] [--interactive]
     [--launch-profile <NAME>] [--no-build]
     [--no-dependencies] [--no-launch-profile] [--no-restore]
@@ -53,6 +53,14 @@ To run the application, the `dotnet run` command resolves the dependencies of th
 
 [!INCLUDE [cli-advertising-manifests](../../../includes/cli-advertising-manifests.md)]
 
+## Arguments
+
+  `<applicationArguments>`
+  
+  Arguments passed to the application that is being run.
+  
+  Any arguments that aren't recognized by `dotnet run` are passed to the application. To separate arguments for `dotnet run` from arguments for the application, use the `--` option.
+
 ## Options
 
 - **`--`**
@@ -75,6 +83,24 @@ To run the application, the `dotnet run` command resolves the dependencies of th
 
   Builds and runs the app using the specified [framework](../../standard/frameworks.md). The framework must be specified in the project file.
 
+- **`--file <FILE_PATH>`**
+
+  The path to the file-based app to run. If a path isn't specified, the current directory is used to find and run the file. For more information on file-based apps, see [Build file-based C# apps](/dotnet/csharp/fundamentals/tutorials/file-based-programs).
+  
+  On Unix, you can run file-based apps directly, using the source file name on the command line instead of `dotnet run`. First, ensure the file has execute permissions. Then, add a shebang line `#!` as the first line of the file, for example:
+  
+  ```csharp
+  #!/usr/bin/env dotnet run
+  ```
+  
+  Then you can run the file directly from the command line:
+  
+  ```bash
+  ./ConsoleApp.cs
+  ```
+
+  Introduced in .NET SDK 10.0.100.
+
 - **`--force`**
 
   Forces all dependencies to be resolved even if the last restore was successful. Specifying this flag is the same as deleting the *project.assets.json* file.
@@ -155,6 +181,14 @@ The environment is constructed in the same order as this list, so the `-e|--envi
   dotnet run
   ```
 
+- Run the specified file-based app in the current directory:
+
+  ```dotnetcli
+  dotnet run --file ConsoleApp.cs
+  ```
+
+  File-based app support was added in .NET SDK 10.0.100.
+
 - Run the specified project:
 
   ```dotnetcli
@@ -178,3 +212,16 @@ The environment is constructed in the same order as this list, so the `-e|--envi
   ```dotnetcli
   dotnet run --verbosity m
   ```
+
+- Run the project in the current directory using the specified framework and pass arguments to the application:
+
+  ```dotnetcli
+  dotnet run -f net6.0 -- arg1 arg2
+  ```
+
+  In the following example, three arguments are passed to the application. One argument is passed using `-`, and two arguments are passed after `--`:
+
+  ```dotnetcli
+  dotnet run -f net6.0 -arg1 -- arg2 arg3
+  ```
+  
diff --git a/includes/cli-arguments-project-solution-file.md b/includes/cli-arguments-project-solution-file.md
