From af995840416b15c600f1e88f084d0883ff61f3cd Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Tue, 16 Dec 2025 16:09:14 -0800 Subject: [PATCH 1/7] update article based on review feedback --- docs/core/sdk/file-based-apps.md | 63 ++++++++++++++++++++++---------- 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 635b5ab775b83..2ef75463e9a0e 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -29,7 +29,7 @@ Adds a NuGet package reference to your application. ```csharp #:package Newtonsoft.Json -#:package Serilog version="3.1.1" +#:package Serilog@3.1.1 ``` ### `#:project` @@ -55,6 +55,7 @@ Specifies the SDK to use. Defaults to `Microsoft.NET.Sdk`. ```csharp #:sdk Microsoft.NET.Sdk.Web +#:sdk Aspire.AppHost.Sdk@13.0.2 ``` ## CLI commands @@ -63,7 +64,13 @@ The .NET CLI provides full support for file-based apps through familiar commands ### Run applications -Run a file-based app directly by using the `dotnet run` command: +Run a file-based app by using the `dotnet run` command with the `--file` option: + +```dotnetcli +dotnet run --file file.cs +``` + +Or use the `dotnet run` command: ```dotnetcli dotnet run file.cs @@ -77,7 +84,7 @@ dotnet file.cs #### Pass arguments -Pass arguments to your application in several ways: +It's recommended to pass arguments to your application by placing them after `--`: ```dotnetcli dotnet run file.cs -- arg1 arg2 @@ -89,12 +96,6 @@ Arguments after `--` are passed to your application. Without `--`, arguments go dotnet run file.cs arg1 arg2 ``` -However, with the shorthand syntax, all arguments go to your application: - -```dotnetcli -dotnet file.cs arg1 arg2 -``` - ### Build applications Compile your file-based app by using the `dotnet build` command: @@ -103,7 +104,7 @@ Compile your file-based app by using the `dotnet build` command: dotnet build file.cs ``` -The SDK generates a temporary project and builds your application. +The SDK generates a virtual project and builds your application. The default path for the build output is `./bin///`. Use the `--output` option to specify a different path. ### Clean build outputs @@ -113,21 +114,29 @@ Remove build artifacts by using the `dotnet clean` command: dotnet clean file.cs ``` -Clean all file-based apps in a directory: +Deletes cache for file-based apps in a directory: ```dotnetcli dotnet clean file-based-apps ``` +Use the `--days` option to specify how many days an artifact folder needs to be unused before removal: + +```dotnetcli +dotnet clean file-based-apps --days 21 +``` + ### Publish applications -Create a deployment package by using the `dotnet publish` command: +File-based apps enable native AOT publishing by default, producing optimized, self-contained executables. Disable this feature by adding `#:property PublishAot=false` at the top of your file. + +Use the `dotnet publish` command to create an independent executable: ```dotnetcli dotnet publish file.cs ``` -File-based apps enable native AOT publishing by default, producing optimized, self-contained executables. +The default location of the executable is an `artifacts` directory next to the .cs file, with a subdirectory named after the application. ### Package as tool @@ -137,7 +146,7 @@ Package your file-based app as a .NET tool by using the `dotnet pack` command: dotnet pack file.cs ``` -File-based apps set `PackAsTool=true` by default. +File-based apps set `PackAsTool=true` by default. Disable this setting by adding `#:property PackAsTool=false` at the top of your file. ### Convert to project @@ -147,7 +156,7 @@ Convert your file-based app to a traditional project by using the `dotnet projec dotnet project convert file.cs ``` -This command creates a `.csproj` file with equivalent SDK and properties. All `#` directives are removed from the `.cs` file and turned into elements in the corresponding `.csproj` file. +This command creates a `.csproj` file with equivalent SDK and properties. The command removes all `#:` directives from the `.cs` file and turns them into elements in the corresponding `.csproj` file. ### Restore dependencies @@ -157,7 +166,7 @@ Restore NuGet packages referenced in your file by using the `dotnet restore` com dotnet restore file.cs ``` -Restore runs implicitly when you build or run your application. +By default, restore runs implicitly when you build or run your application. However, you can pass `--no-restore` to both the `dotnet build` and `dotnet run` commands to build or run without implicitly restoring. ## Default included items @@ -192,7 +201,13 @@ File-based apps generate a stable user secrets ID based on a hash of the full fi Access user secrets the same way as traditional projects: ```dotnetcli -dotnet user-secrets set "ApiKey" "your-secret-value" --project file.cs +dotnet user-secrets set "ApiKey" "your-secret-value" --file file.cs +``` + +List user secrets for file-based apps: + +```dotnetcli +dotnet user-secrets list --file file.cs ``` For more information, see [Safe storage of app secrets in development](/aspnet/core/security/app-secrets). @@ -287,6 +302,9 @@ Run directly: ./file.cs ``` +> [!NOTE] +> Adding a shebang requires that you use `LF` line endings instead of `CRLF` and that the file doesn't contain a BOM. + ## Implicit build files File-based apps respect MSBuild and NuGet configuration files in the same directory or parent directories. These files affect how the SDK builds your application. Be mindful of these files when organizing your file-based apps. @@ -313,7 +331,7 @@ Specifies the .NET SDK version to use. File-based apps respect this version sele ## Build caching -The .NET SDK caches build outputs to improve performance on subsequent builds. File-based apps participate in this caching system. +The .NET SDK caches build outputs to improve performance on subsequent builds. This caching system is unique to file-based apps. ### Cache behavior @@ -321,8 +339,7 @@ The SDK caches build outputs based on: - Source file content. - Directive configuration. -- SDK version. -- Implicit build files. +- SDK version.- Implicit build files existence and content. Caching improves build performance but can cause confusion when: @@ -331,6 +348,12 @@ Caching improves build performance but can cause confusion when: ### Workarounds +- Clear cache artifacts for file-based apps by using the following command: + +```dotnetcli +dotnet clean file-based-apps +``` + - Run a full build by using the `--no-cache` flag: ```dotnetcli From b02a09ec144ef42e5fab8eb6eceb27990eb08017 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Tue, 16 Dec 2025 16:29:10 -0800 Subject: [PATCH 2/7] edit pass --- docs/core/sdk/file-based-apps.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 2ef75463e9a0e..fb4b91d8b0d81 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -70,7 +70,7 @@ Run a file-based app by using the `dotnet run` command with the `--file` option: dotnet run --file file.cs ``` -Or use the `dotnet run` command: +Or use the `dotnet run` command followed by the name of the file: ```dotnetcli dotnet run file.cs @@ -90,7 +90,7 @@ It's recommended to pass arguments to your application by placing them after `-- dotnet run file.cs -- arg1 arg2 ``` -Arguments after `--` are passed to your application. Without `--`, arguments go to the `dotnet run` command: +Without `--`, arguments go to the `dotnet run` command: ```dotnetcli dotnet run file.cs arg1 arg2 @@ -114,17 +114,13 @@ Remove build artifacts by using the `dotnet clean` command: dotnet clean file.cs ``` -Deletes cache for file-based apps in a directory: +Delete cache for file-based apps in a directory: ```dotnetcli dotnet clean file-based-apps ``` -Use the `--days` option to specify how many days an artifact folder needs to be unused before removal: - -```dotnetcli -dotnet clean file-based-apps --days 21 -``` +Use the `--days` option with the preceding command to specify how many days an artifact folder needs to be unused before removal. The default number of days is 30. ### Publish applications @@ -136,7 +132,7 @@ Use the `dotnet publish` command to create an independent executable: dotnet publish file.cs ``` -The default location of the executable is an `artifacts` directory next to the .cs file, with a subdirectory named after the application. +The default location of the executable is an `artifacts` directory next to the `.cs` file, with a subdirectory named after the application. ### Package as tool @@ -339,7 +335,7 @@ The SDK caches build outputs based on: - Source file content. - Directive configuration. -- SDK version.- Implicit build files existence and content. +- SDK version. Implicit build files existence and content. Caching improves build performance but can cause confusion when: From 4214105e9599e3dad8ff1f6db747f20d7fd704ea Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Wed, 17 Dec 2025 09:00:57 -0800 Subject: [PATCH 3/7] fix review feedback --- docs/core/sdk/file-based-apps.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index fb4b91d8b0d81..5483bfa04cb3a 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -84,7 +84,7 @@ dotnet file.cs #### Pass arguments -It's recommended to pass arguments to your application by placing them after `--`: +Pass arguments to your application by placing them after `--`: ```dotnetcli dotnet run file.cs -- arg1 arg2 @@ -104,7 +104,7 @@ Compile your file-based app by using the `dotnet build` command: dotnet build file.cs ``` -The SDK generates a virtual project and builds your application. The default path for the build output is `./bin///`. Use the `--output` option to specify a different path. +The SDK generates a virtual project and builds your application. The default path for the build output is `C:\Users\\AppData\Local\Temp\dotnet\runfile\-\bin\debug\`. Use the `--output` option to specify a different path. ### Clean build outputs @@ -132,7 +132,7 @@ Use the `dotnet publish` command to create an independent executable: dotnet publish file.cs ``` -The default location of the executable is an `artifacts` directory next to the `.cs` file, with a subdirectory named after the application. +The default location of the executable is an `artifacts` directory next to the `.cs` file, with a subdirectory named after the application. Use the `--output` option to specify a different path. ### Package as tool @@ -152,7 +152,7 @@ Convert your file-based app to a traditional project by using the `dotnet projec dotnet project convert file.cs ``` -This command creates a `.csproj` file with equivalent SDK and properties. The command removes all `#:` directives from the `.cs` file and turns them into elements in the corresponding `.csproj` file. +The command makes a copy of the `.cs` file and creates a `.csproj` file with equivalent SDK and properties. The `#:` directives are removed, and turned into elements in the corresponding `.csproj` file. The original `.cs` file is left untouched. ### Restore dependencies @@ -180,7 +180,7 @@ Different SDKs include other file types: ## Native AOT publishing -File-based apps enable native ahead-of-time (AOT) compilation by default. This feature produces optimized, self-contained executables with faster startup and a smaller memory footprint. +File-based apps enable native ahead-of-time (AOT) compilation by default. This feature produces optimized, self-contained executables with faster startup, and a smaller memory footprint. If you need to disable native AOT, use the following setting: @@ -327,7 +327,7 @@ Specifies the .NET SDK version to use. File-based apps respect this version sele ## Build caching -The .NET SDK caches build outputs to improve performance on subsequent builds. This caching system is unique to file-based apps. +The .NET SDK caches build outputs to improve performance on subsequent invocations of `dotnet run`. This caching system is unique to file-based apps. ### Cache behavior @@ -335,7 +335,8 @@ The SDK caches build outputs based on: - Source file content. - Directive configuration. -- SDK version. Implicit build files existence and content. +- SDK version. +- Implicit build files existence and content. Caching improves build performance but can cause confusion when: From aef8abc097d1cb7b546ef7c3254a50eb579b8e33 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Wed, 17 Dec 2025 09:08:06 -0800 Subject: [PATCH 4/7] clarify path output details --- docs/core/sdk/file-based-apps.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 5483bfa04cb3a..fded5d6177b9b 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -104,7 +104,9 @@ Compile your file-based app by using the `dotnet build` command: dotnet build file.cs ``` -The SDK generates a virtual project and builds your application. The default path for the build output is `C:\Users\\AppData\Local\Temp\dotnet\runfile\-\bin\debug\`. Use the `--output` option to specify a different path. +The SDK generates a virtual project and builds your application. The default path for the build output is `C:\Users\\AppData\Local\Temp\dotnet\runfile\-\bin\debug\`. + +Use the `--output` option with the `dotnet build` command to specify a different path. Alternatively, set the `OutoutPath` property in the file-based app by using the directive: `#:property OutputPath=./output` ### Clean build outputs @@ -132,7 +134,7 @@ Use the `dotnet publish` command to create an independent executable: dotnet publish file.cs ``` -The default location of the executable is an `artifacts` directory next to the `.cs` file, with a subdirectory named after the application. Use the `--output` option to specify a different path. +The default location of the executable is an `artifacts` directory next to the `.cs` file, with a subdirectory named after the application. Use the `--output` option with the `dotnet publish` command to specify a different path. ### Package as tool @@ -152,7 +154,7 @@ Convert your file-based app to a traditional project by using the `dotnet projec dotnet project convert file.cs ``` -The command makes a copy of the `.cs` file and creates a `.csproj` file with equivalent SDK and properties. The `#:` directives are removed, and turned into elements in the corresponding `.csproj` file. The original `.cs` file is left untouched. +This command makes a copy of the `.cs` file and creates a `.csproj` file with equivalent SDK and properties. The `#:` directives are removed, and turned into elements in the corresponding `.csproj` file. The original `.cs` file is left untouched. ### Restore dependencies From cd91d75bc58e220da877cd7632bdf4b9c8922c6d Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Wed, 17 Dec 2025 09:17:02 -0800 Subject: [PATCH 5/7] add period to end of sentence --- docs/core/sdk/file-based-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index fded5d6177b9b..0efbfcb8fa443 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -106,7 +106,7 @@ dotnet build file.cs The SDK generates a virtual project and builds your application. The default path for the build output is `C:\Users\\AppData\Local\Temp\dotnet\runfile\-\bin\debug\`. -Use the `--output` option with the `dotnet build` command to specify a different path. Alternatively, set the `OutoutPath` property in the file-based app by using the directive: `#:property OutputPath=./output` +Use the `--output` option with the `dotnet build` command to specify a different path. Alternatively, set the `OutoutPath` property in the file by using the directive: `#:property OutputPath=./output`. ### Clean build outputs From 2fa0147e5a4eaaef5b373ccf5e3c8bc0f1542855 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Wed, 17 Dec 2025 11:34:40 -0800 Subject: [PATCH 6/7] edit pass --- docs/core/sdk/file-based-apps.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 0efbfcb8fa443..5efc6aa16eb13 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -104,9 +104,9 @@ Compile your file-based app by using the `dotnet build` command: dotnet build file.cs ``` -The SDK generates a virtual project and builds your application. The default path for the build output is `C:\Users\\AppData\Local\Temp\dotnet\runfile\-\bin\debug\`. +The SDK generates a virtual project and builds your application. By default, the build output goes to the system's temporary directory under `/dotnet/runfile/-/bin//`. -Use the `--output` option with the `dotnet build` command to specify a different path. Alternatively, set the `OutoutPath` property in the file by using the directive: `#:property OutputPath=./output`. +Use the `--output` option with the `dotnet build` command to specify a different path. To define a new default output path, set the `OutputPath` property at the top of your file by using the directive: `#:property OutputPath=./output`. ### Clean build outputs @@ -154,7 +154,7 @@ Convert your file-based app to a traditional project by using the `dotnet projec dotnet project convert file.cs ``` -This command makes a copy of the `.cs` file and creates a `.csproj` file with equivalent SDK and properties. The `#:` directives are removed, and turned into elements in the corresponding `.csproj` file. The original `.cs` file is left untouched. +This command makes a copy of the `.cs` file and creates a `.csproj` file with equivalent SDK items, properties, and package references based on the original file's `#:` directives. Both files are placed in a directory named for the application next to the original `.cs` file, which is left untouched. ### Restore dependencies @@ -182,7 +182,7 @@ Different SDKs include other file types: ## Native AOT publishing -File-based apps enable native ahead-of-time (AOT) compilation by default. This feature produces optimized, self-contained executables with faster startup, and a smaller memory footprint. +File-based apps enable native ahead-of-time (AOT) compilation by default. This feature produces optimized, self-contained executables with faster startup and a smaller memory footprint. If you need to disable native AOT, use the following setting: @@ -301,7 +301,7 @@ Run directly: ``` > [!NOTE] -> Adding a shebang requires that you use `LF` line endings instead of `CRLF` and that the file doesn't contain a BOM. +> Use `LF` line endings instead of `CRLF` when you add a shebang. Don't include a BOM in the file. ## Implicit build files @@ -338,7 +338,7 @@ The SDK caches build outputs based on: - Source file content. - Directive configuration. - SDK version. -- Implicit build files existence and content. +- Implicit build file existence and content. Caching improves build performance but can cause confusion when: From 62d4c617a0039a33be3fd7cfe7ec07ed45ffcc53 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Thu, 18 Dec 2025 09:27:55 -0800 Subject: [PATCH 7/7] Add note about dotnet user-secrets list command --- docs/core/sdk/file-based-apps.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 5efc6aa16eb13..0d8013a54e328 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -208,6 +208,8 @@ List user secrets for file-based apps: dotnet user-secrets list --file file.cs ``` +The `dotnet user-secrets list` command prints the value of your secrets. Don't put this command in scripts that run in public contexts. + For more information, see [Safe storage of app secrets in development](/aspnet/core/security/app-secrets). ## Launch profiles