From aed80f6fc62cfc43f09e14d64f0f1acb146c0fa0 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Fri, 5 Dec 2025 16:12:52 -0800 Subject: [PATCH 1/6] add file-based apps reference --- docs/core/sdk/file-based-apps.md | 349 ++++++++++++++++++++++++ docs/navigate/tools-diagnostics/toc.yml | 2 + 2 files changed, 351 insertions(+) create mode 100644 docs/core/sdk/file-based-apps.md diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md new file mode 100644 index 0000000000000..6c1e312dfdc5b --- /dev/null +++ b/docs/core/sdk/file-based-apps.md @@ -0,0 +1,349 @@ +--- +title: File-based C# apps +description: Learn how to create, build, and run C# applications from a single file without a project file. +ms.date: 12/05/2025 +ai-usage: ai-assisted +--- +# File-based C# apps + +**This article applies to:** ✔️ .NET 10 SDK and later versions + +File-based apps let you build, run, and publish .NET applications from a single C# file without creating a traditional project file. This approach simplifies development for scripts, utilities, and small applications. The .NET SDK automatically generates the necessary project configuration based on directives in your source file. + +## Overview + +File-based apps offer a lightweight alternative to traditional .NET projects. Instead of maintaining separate `.csproj` files, you embed configuration directly in your C# source file using special directives. The .NET CLI processes these directives to build and run your application. + +Key benefits include: + +- Reduced boilerplate for simple applications +- Self-contained source files with embedded configuration +- Native AOT publishing enabled by default +- Automatic packaging as .NET tools + +## Supported directives + +File-based apps use directives prefixed with `#:` to configure the build. Place these directives at the top of your C# file. + +### `#:package` + +Adds a NuGet package reference to your application. + +```csharp +#:package Newtonsoft.Json +#:package Serilog version="3.1.1" +``` + +### `#:property` + +Sets an MSBuild property value. + +```csharp +#:property TargetFramework=net9.0 +#:property PublishAot=false +``` + +### `#:sdk` + +Specifies the SDK to use. Defaults to `Microsoft.NET.Sdk`. + +```csharp +#:sdk Microsoft.NET.Sdk.Web +``` + +### `#:project` + +References another project file. + +```csharp +#:project ../SharedLibrary/SharedLibrary.csproj +``` + +## CLI commands + +The .NET CLI provides full support for file-based apps through familiar commands. + +### Run applications + +Run a file-based app directly: + +```dotnetcli +dotnet run file.cs +``` + +Or use the shorthand syntax: + +```dotnetcli +dotnet file.cs +``` + +#### Pass arguments + +Pass arguments to your application in several ways: + +```dotnetcli +dotnet run file.cs -- arg1 arg2 +``` + +Arguments after `--` are passed to your application. Without `--`, arguments go to the `dotnet run` command: + +```dotnetcli +dotnet run file.cs arg1 arg2 +``` + +With the shorthand syntax, all arguments go to your application: + +```dotnetcli +dotnet file.cs arg1 arg2 +``` + +### Restore dependencies + +Restore NuGet packages referenced in your file: + +```dotnetcli +dotnet restore file.cs +``` + +Restore runs implicitly when you build or run your application. + +### Build applications + +Compile your file-based app: + +```dotnetcli +dotnet build file.cs +``` + +The SDK generates a temporary project and builds your application. + +### Publish applications + +Create a deployment package: + +```dotnetcli +dotnet publish file.cs +``` + +File-based apps enable native AOT publishing by default, producing optimized, self-contained executables. + +### Package as tool + +Package your file-based app as a .NET tool: + +```dotnetcli +dotnet pack file.cs +``` + +File-based apps set `PackAsTool=true` by default. + +### Convert to project + +Convert your file-based app to a traditional project: + +```dotnetcli +dotnet project convert file.cs +``` + +This command creates a `.csproj` file with equivalent configuration. + +### Clean build outputs + +Remove build artifacts: + +```dotnetcli +dotnet clean file.cs +``` + +Clean all file-based apps in a directory: + +```dotnetcli +dotnet clean file-based-apps +``` + +## Default included items + +File-based apps automatically include specific file types for compilation and packaging. + +### Standard includes + +By default, the following items are included: + +- The single C# file itself +- ResX resource files in the same directory + +### SDK-specific includes + +Different SDKs include additional file types: + +- `Microsoft.NET.Sdk.Web` includes `*.json` configuration files +- Other specialized SDKs might include additional patterns + +## Native AOT publishing + +File-based apps enable native ahead-of-time (AOT) compilation by default. This produces optimized, self-contained executables with faster startup and smaller memory footprint. + +Disable native AOT if needed: + +```csharp +#:property PublishAot=false +``` + +For more information about native AOT, see [Native AOT deployment](../deploying/native-aot/index.md). + +## User secrets + +File-based apps generate a stable user secrets ID based on a hash of the full file path. This lets you store sensitive configuration separately from your source code. + +Access user secrets the same way as traditional projects: + +```dotnetcli +dotnet user-secrets set "ApiKey" "your-secret-value" --project file.cs +``` + +For more information, see [Safe storage of app secrets in development](/aspnet/core/security/app-secrets). + +## Shell execution + +Enable direct execution of file-based apps on Unix-like systems using a shebang line and executable permissions. + +Add a shebang at the top of your file: + +```csharp +#!/usr/bin/env dotnet +#:package Spectre.Console + +using Spectre.Console; + +AnsiConsole.MarkupLine("[green]Hello, World![/]"); +``` + +Make the file executable: + +```bash +chmod +x file.cs +``` + +Run directly: + +```bash +./file.cs +``` + +## 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. + +### `Directory.Build.props` + +Defines MSBuild properties that apply to all projects in a directory tree. File-based apps inherit these properties. + +### `Directory.Build.targets` + +Defines MSBuild targets and custom build logic. File-based apps execute these targets during build. + +### `Directory.Packages.props` + +Enables central package management for NuGet dependencies. File-based apps can use centrally managed package versions. + +### `nuget.config` + +Configures NuGet package sources and settings. File-based apps use these configurations when restoring packages. + +### `global.json` + +Specifies the .NET SDK version to use. File-based apps respect this version selection. + +Be mindful of these files when organizing your file-based apps. They can unexpectedly affect build behavior. + +## Build caching + +The .NET SDK caches build outputs to improve performance on subsequent builds. File-based apps participate in this caching system. + +### Cache behavior + +Build outputs are cached based on: + +- Source file content +- Directive configuration +- SDK version +- Implicit build files + +### Cache impacts + +Caching improves build performance but can cause confusion: + +- Changes to implicit build files might not trigger rebuilds +- Moving files to different directories might not invalidate cache + +### Workarounds + +Force a clean build to bypass cache: + +```dotnetcli +dotnet clean file.cs +dotnet build file.cs +``` + +Or delete the `obj` and `bin` directories manually. + +## Folder layout recommendations + +Organize your file-based apps carefully to avoid conflicts with traditional projects and implicit build files. + +### Avoid project file cones + +Don't place file-based apps within the directory structure of a `.csproj` project. The project file's implicit build files and settings can interfere with your file-based app. + +❌ **Not recommended:** + +``` +MyProject/ +├── MyProject.csproj +├── Program.cs +└── scripts/ + └── utility.cs // File-based app - bad location +``` + +✅ **Recommended:** + +``` +MyProject/ +├── MyProject.csproj +└── Program.cs +scripts/ +└── utility.cs // File-based app - good location +``` + +### Be mindful of implicit files + +Implicit build files in parent directories affect all file-based apps in subdirectories. Create isolated directories for file-based apps when you need different build configurations. + +❌ **Not recommended:** + +``` +repo/ +├── Directory.Build.props // Affects everything below +├── app1.cs +└── app2.cs +``` + +✅ **Recommended:** + +``` +repo/ +├── Directory.Build.props +├── projects/ +│ └── MyProject.csproj +└── scripts/ + ├── Directory.Build.props // Isolated configuration + ├── app1.cs + └── app2.cs +``` + +## See also + +- [.NET CLI overview](index.md) +- [dotnet run command](dotnet-run.md) +- [dotnet build command](dotnet-build.md) +- [Native AOT deployment](../deploying/native-aot/index.md) diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index ff1cadc83aa13..43501e2c14d13 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -9,6 +9,8 @@ items: href: ../../core/sdk.md - name: Environment variables href: ../../core/tools/dotnet-environment-variables.md + - name: File-based apps + href: ../../core/sdk/file-based-apps.md - name: dotnet-install scripts href: ../../core/tools/dotnet-install-script.md - name: global.json overview From 2df663049bdb546a3cda9364d740425dbc41b574 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Mon, 8 Dec 2025 09:08:11 -0800 Subject: [PATCH 2/6] fix links --- docs/core/sdk/file-based-apps.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 6c1e312dfdc5b..45fcab34ecfed 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -1,10 +1,10 @@ --- -title: File-based C# apps +title: File-based apps description: Learn how to create, build, and run C# applications from a single file without a project file. ms.date: 12/05/2025 ai-usage: ai-assisted --- -# File-based C# apps +# File-based apps **This article applies to:** ✔️ .NET 10 SDK and later versions @@ -183,7 +183,7 @@ Different SDKs include additional file types: File-based apps enable native ahead-of-time (AOT) compilation by default. This produces optimized, self-contained executables with faster startup and smaller memory footprint. -Disable native AOT if needed: +If you need to disable native AOT, use the following setting: ```csharp #:property PublishAot=false @@ -193,7 +193,7 @@ For more information about native AOT, see [Native AOT deployment](../deploying/ ## User secrets -File-based apps generate a stable user secrets ID based on a hash of the full file path. This lets you store sensitive configuration separately from your source code. +File-based apps generate a stable user secrets ID based on a hash of the full file path. This ID lets you store sensitive configuration separately from your source code. Access user secrets the same way as traditional projects: @@ -205,7 +205,7 @@ For more information, see [Safe storage of app secrets in development](/aspnet/c ## Shell execution -Enable direct execution of file-based apps on Unix-like systems using a shebang line and executable permissions. +Enable direct execution of file-based apps on Unix-like systems by using a shebang line and executable permissions. Add a shebang at the top of your file: @@ -262,7 +262,7 @@ The .NET SDK caches build outputs to improve performance on subsequent builds. F ### Cache behavior -Build outputs are cached based on: +The SDK caches build outputs based on: - Source file content - Directive configuration @@ -343,7 +343,7 @@ repo/ ## See also -- [.NET CLI overview](index.md) -- [dotnet run command](dotnet-run.md) -- [dotnet build command](dotnet-build.md) +- [.NET SDK overview](../sdk.md) +- [dotnet run command](../toolsdotnet-run.md) +- [dotnet build command](../toolsdotnet-build.md) - [Native AOT deployment](../deploying/native-aot/index.md) From fcaa9ff221062a0ead2ce0e99b88414d89bed944 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Mon, 8 Dec 2025 09:24:19 -0800 Subject: [PATCH 3/6] fix links --- docs/core/sdk/file-based-apps.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 45fcab34ecfed..8228fae806b9d 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -344,6 +344,6 @@ repo/ ## See also - [.NET SDK overview](../sdk.md) -- [dotnet run command](../toolsdotnet-run.md) -- [dotnet build command](../toolsdotnet-build.md) +- [dotnet run command](../tools/dotnet-run.md) +- [dotnet build command](../tools/dotnet-build.md) - [Native AOT deployment](../deploying/native-aot/index.md) From 503a525ba0d3d0c6cc74c5859d30164725bbd831 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Tue, 9 Dec 2025 12:16:36 -0800 Subject: [PATCH 4/6] edit pass --- docs/core/sdk/file-based-apps.md | 122 +++++++++++++++---------------- 1 file changed, 58 insertions(+), 64 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 8228fae806b9d..26f0364ca598c 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -8,22 +8,20 @@ ai-usage: ai-assisted **This article applies to:** ✔️ .NET 10 SDK and later versions -File-based apps let you build, run, and publish .NET applications from a single C# file without creating a traditional project file. This approach simplifies development for scripts, utilities, and small applications. The .NET SDK automatically generates the necessary project configuration based on directives in your source file. - -## Overview - -File-based apps offer a lightweight alternative to traditional .NET projects. Instead of maintaining separate `.csproj` files, you embed configuration directly in your C# source file using special directives. The .NET CLI processes these directives to build and run your application. +File-based apps let you build, run, and publish .NET applications from a single C# file without creating a traditional project file. They offer a lightweight alternative to traditional .NET projects. This approach simplifies development for scripts, utilities, and small applications. The .NET SDK automatically generates the necessary project configuration based on the directives in your source file. Key benefits include: -- Reduced boilerplate for simple applications -- Self-contained source files with embedded configuration -- Native AOT publishing enabled by default -- Automatic packaging as .NET tools +- Reduced boilerplate for simple applications. +- Self-contained source files with embedded configuration. +- Native AOT publishing enabled by default. +- Automatic packaging as .NET tools. + +In this article, learn more about how to use file-based apps successfully. ## Supported directives -File-based apps use directives prefixed with `#:` to configure the build. Place these directives at the top of your C# file. +File-based apps use directives prefixed with `#:` to configure the build and run your application. Supported directives include: `#:package`, `#:project`, `#:property`, and `#:sdk`. Place these directives at the top of your C# file. ### `#:package` @@ -34,29 +32,29 @@ Adds a NuGet package reference to your application. #:package Serilog version="3.1.1" ``` -### `#:property` +### `#:project` -Sets an MSBuild property value. +References another project file. ```csharp -#:property TargetFramework=net9.0 -#:property PublishAot=false +#:project ../SharedLibrary/SharedLibrary.csproj ``` -### `#:sdk` +### `#:property` -Specifies the SDK to use. Defaults to `Microsoft.NET.Sdk`. +Sets a MSBuild property value. ```csharp -#:sdk Microsoft.NET.Sdk.Web +#:property TargetFramework=net10.0 +#:property PublishAot=false ``` -### `#:project` +### `#:sdk` -References another project file. +Specifies the SDK to use. Defaults to `Microsoft.NET.Sdk`. ```csharp -#:project ../SharedLibrary/SharedLibrary.csproj +#:sdk Microsoft.NET.Sdk.Web ``` ## CLI commands @@ -65,7 +63,7 @@ The .NET CLI provides full support for file-based apps through familiar commands ### Run applications -Run a file-based app directly: +Run a file-based app directly using the `dotnet run` command: ```dotnetcli dotnet run file.cs @@ -97,29 +95,33 @@ With the shorthand syntax, all arguments go to your application: dotnet file.cs arg1 arg2 ``` -### Restore dependencies +### Build applications -Restore NuGet packages referenced in your file: +Compile your file-based app using the `dotnet build` command: ```dotnetcli -dotnet restore file.cs +dotnet build file.cs ``` -Restore runs implicitly when you build or run your application. +The SDK generates a temporary project and builds your application. -### Build applications +### Clean build outputs -Compile your file-based app: +Remove build artifacts using the `dotnet clean` command: ```dotnetcli -dotnet build file.cs +dotnet clean file.cs ``` -The SDK generates a temporary project and builds your application. +Clean all file-based apps in a directory: + +```dotnetcli +dotnet clean file-based-apps +``` ### Publish applications -Create a deployment package: +Create a deployment package using the `dotnet publish` command: ```dotnetcli dotnet publish file.cs @@ -129,7 +131,7 @@ File-based apps enable native AOT publishing by default, producing optimized, se ### Package as tool -Package your file-based app as a .NET tool: +Package your file-based app as a .NET tool using the `dotnet pack` command: ```dotnetcli dotnet pack file.cs @@ -139,49 +141,41 @@ File-based apps set `PackAsTool=true` by default. ### Convert to project -Convert your file-based app to a traditional project: +Convert your file-based app to a traditional project using the `dotnet project convert` command: ```dotnetcli dotnet project convert file.cs ``` -This command creates a `.csproj` file with equivalent configuration. +This command creates a `.csproj` file with equivalent SDK and properties. All `#` directives are removed from the `.cs` files and turned into elements in the corresponding `.csproj` files. -### Clean build outputs +### Restore dependencies -Remove build artifacts: +Restore NuGet packages referenced in your file using the `dotnet restore` command: ```dotnetcli -dotnet clean file.cs +dotnet restore file.cs ``` -Clean all file-based apps in a directory: - -```dotnetcli -dotnet clean file-based-apps -``` +Restore runs implicitly when you build or run your application. ## Default included items File-based apps automatically include specific file types for compilation and packaging. -### Standard includes - By default, the following items are included: -- The single C# file itself -- ResX resource files in the same directory - -### SDK-specific includes +- The single C# file itself. +- ResX resource files in the same directory. -Different SDKs include additional file types: +Different SDKs include other file types: -- `Microsoft.NET.Sdk.Web` includes `*.json` configuration files -- Other specialized SDKs might include additional patterns +- `Microsoft.NET.Sdk.Web` includes `*.json` configuration files. +- Other specialized SDKs might include other patterns. ## Native AOT publishing -File-based apps enable native ahead-of-time (AOT) compilation by default. This produces optimized, self-contained executables with faster startup and 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: @@ -232,7 +226,7 @@ Run directly: ## 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. +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. ### `Directory.Build.props` @@ -254,8 +248,6 @@ Configures NuGet package sources and settings. File-based apps use these configu Specifies the .NET SDK version to use. File-based apps respect this version selection. -Be mindful of these files when organizing your file-based apps. They can unexpectedly affect build behavior. - ## Build caching The .NET SDK caches build outputs to improve performance on subsequent builds. File-based apps participate in this caching system. @@ -269,23 +261,25 @@ The SDK caches build outputs based on: - SDK version - Implicit build files -### Cache impacts - Caching improves build performance but can cause confusion: -- Changes to implicit build files might not trigger rebuilds -- Moving files to different directories might not invalidate cache +- Changes to implicit build files might not trigger rebuilds. +- Moving files to different directories might not invalidate cache. ### Workarounds -Force a clean build to bypass cache: +- Run a full build using the `--no-cache` flag: -```dotnetcli -dotnet clean file.cs -dotnet build file.cs -``` + ```dotnetcli + dotnet build file.cs --no-cache + ``` + +- Force a clean build to bypass cache: -Or delete the `obj` and `bin` directories manually. + ```dotnetcli + dotnet clean file.cs + dotnet build file.cs + ``` ## Folder layout recommendations From 2a9c0655994c78e1dc15f01ae0eb89957921149d Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Tue, 9 Dec 2025 12:49:54 -0800 Subject: [PATCH 5/6] edit pass --- docs/core/sdk/file-based-apps.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index 26f0364ca598c..42361064ea0fa 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -17,7 +17,7 @@ Key benefits include: - Native AOT publishing enabled by default. - Automatic packaging as .NET tools. -In this article, learn more about how to use file-based apps successfully. +In this article, learn how to create, configure, and work with file-based apps effectively. ## Supported directives @@ -63,7 +63,7 @@ The .NET CLI provides full support for file-based apps through familiar commands ### Run applications -Run a file-based app directly using the `dotnet run` command: +Run a file-based app directly by using the `dotnet run` command: ```dotnetcli dotnet run file.cs @@ -97,7 +97,7 @@ dotnet file.cs arg1 arg2 ### Build applications -Compile your file-based app using the `dotnet build` command: +Compile your file-based app by using the `dotnet build` command: ```dotnetcli dotnet build file.cs @@ -107,7 +107,7 @@ The SDK generates a temporary project and builds your application. ### Clean build outputs -Remove build artifacts using the `dotnet clean` command: +Remove build artifacts by using the `dotnet clean` command: ```dotnetcli dotnet clean file.cs @@ -121,7 +121,7 @@ dotnet clean file-based-apps ### Publish applications -Create a deployment package using the `dotnet publish` command: +Create a deployment package by using the `dotnet publish` command: ```dotnetcli dotnet publish file.cs @@ -131,7 +131,7 @@ File-based apps enable native AOT publishing by default, producing optimized, se ### Package as tool -Package your file-based app as a .NET tool using the `dotnet pack` command: +Package your file-based app as a .NET tool by using the `dotnet pack` command: ```dotnetcli dotnet pack file.cs @@ -141,7 +141,7 @@ File-based apps set `PackAsTool=true` by default. ### Convert to project -Convert your file-based app to a traditional project using the `dotnet project convert` command: +Convert your file-based app to a traditional project by using the `dotnet project convert` command: ```dotnetcli dotnet project convert file.cs @@ -151,7 +151,7 @@ This command creates a `.csproj` file with equivalent SDK and properties. All `# ### Restore dependencies -Restore NuGet packages referenced in your file using the `dotnet restore` command: +Restore NuGet packages referenced in your file by using the `dotnet restore` command: ```dotnetcli dotnet restore file.cs @@ -268,7 +268,7 @@ Caching improves build performance but can cause confusion: ### Workarounds -- Run a full build using the `--no-cache` flag: +- Run a full build by using the `--no-cache` flag: ```dotnetcli dotnet build file.cs --no-cache From fe2c006ca5cb0aed5f34057a8c5e642ec81d97b4 Mon Sep 17 00:00:00 2001 From: Meaghan Osagie Date: Wed, 10 Dec 2025 12:18:41 -0800 Subject: [PATCH 6/6] address feedback from copilot --- 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 42361064ea0fa..1a76cd61da056 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -42,7 +42,7 @@ References another project file. ### `#:property` -Sets a MSBuild property value. +Sets the MSBuild property value. ```csharp #:property TargetFramework=net10.0 @@ -256,12 +256,12 @@ The .NET SDK caches build outputs to improve performance on subsequent builds. F The SDK caches build outputs based on: -- Source file content -- Directive configuration -- SDK version -- Implicit build files +- Source file content. +- Directive configuration. +- SDK version. +- Implicit build files. -Caching improves build performance but can cause confusion: +Caching improves build performance but can cause confusion when: - Changes to implicit build files might not trigger rebuilds. - Moving files to different directories might not invalidate cache.