/csharp-scripts

name: csharp-scripts
description: "Run file-based C# apps with the .NET CLI when the user explicitly wants C#/.NET code without creating a project. Use for C# language/API experiments, one-file C# apps, small multi-file C# apps composed with `#:include`/`#:exclude`, or C# file-based apps linked with `#:ref`. Do not use for language-agnostic throwaway scripts, generic computations, Python/PowerShell-style automation, full projects, or existing app integration."
license: MIT

File-Based C# Apps

When to Use

• Testing a C# concept, API, or language feature with a quick file-based app
• Prototyping logic before integrating it into a larger project
• Building a small utility from one entry-point file and a few helper `.cs` files

When Not to Use

• The user asks for a language-agnostic quick script, throwaway computation, or shell/Python/PowerShell-style automation
• The user needs a full project, solution integration, or project references in an existing app
• The user is working inside an existing .NET solution and wants to add code there
• The app is large enough that project structure, build customization, tests, or publish configuration should live in a `.csproj`

Inputs

| Input | Required | Description | |-------|----------|-------------| | C# code or intent | Yes | The code to run, or a description of what the file-based app should do |

Workflow

Step 1: Check the .NET SDK version

Run `dotnet --version` to verify the SDK is installed and note the full version, including the feature band. File-based apps require .NET 10 or later. `#:include`, `#:exclude`, and transitive directive processing require SDK 10.0.300 or later; SDK 10.0.100/10.0.200 builds can run single-file apps but do not support those multi-file directives. If the version is below 10, follow the [fallback for older SDKs](#fallback-for-net-9-and-earlier) instead.

Step 2: Write the app file

Create an entry-point `.cs` file using top-level statements. Place it outside any existing project directory to avoid conflicts with `.csproj` files.

#!/usr/bin/env dotnet
// hello.cs
Console.WriteLine("Hello from a file-based app!");

var numbers = new[] { 1, 2, 3, 4, 5 };
Console.WriteLine($"Sum: {numbers.Sum()}");

Guidelines:

• Use top-level statements (no `Main` method, class, or namespace boilerplate)
• Place `using` directives at the top of the file (after the `#!` line and any `#:` directives if present)
• Place type declarations (classes, records, enums) after all top-level statements

Step 3: Run the app

dotnet hello.cs

Builds and runs the file automatically. Cached so subsequent runs are fast. Pass arguments after `--`:

dotnet hello.cs -- arg1 arg2 "multi word arg"

Step 4: Add directives (if needed)

Place directives at the top of the file (immediately after an optional shebang line), before any `using` directives or other C# code. All directives start with `#:`.

`#:package` — NuGet package references

Specify a version unless the app intentionally uses central package management. Use `@*` when the latest available package is acceptable (or `@*-*` for pre-release):

#:package Humanizer@2.14.1

using Humanizer;

Console.WriteLine("hello world".Titleize());

`#:property` — MSBuild properties

Set any MSBuild property inline. Syntax: `#:property PropertyName=Value`

#:property AllowUnsafeBlocks=true
#:property PublishAot=false
#:property NoWarn=CS0162

MSBuild expressions and property functions are supported:

#:property LogLevel=$([MSBuild]::ValueOrDefault('$(LOG_LEVEL)', 'Information'))

Common properties:

| Property | Purpose | |----------|---------| | `AllowUnsafeBlocks=true` | Enable `unsafe` code | | `PublishAot=false` | Disable native AOT (enabled by default) | | `NoWarn=CS0162;CS0219` | Suppress specific warnings | | `LangVersion=preview` | Enable preview language features | | `InvariantGlobalization=false` | Enable culture-specific globalization |

`#:project` — Project references

Reference another project by relative path:

#:project ../MyLibrary/MyLibrary.csproj

`#:ref` — File-based app references

Reference another `.cs` file as a separate file-based app project when it should compile into a separate assembly instead of being included in the same compilation. Use `#:include` for ordinary helper files that should share the same assembly as the entry point; use `#:ref` when you want project-reference-like boundaries.

#:property ExperimentalFileBasedProgramEnableRefDirective=true
#:ref ../Shared/Formatter.cs

Console.WriteLine(Formatter.Title("hello world"));

Guidelines:

• The referenced file is compiled as its own virtual project and added as a project reference.
• If the referenced file is a library without top-level statements, put `#:property OutputType=Library` in that referenced file.
• Members that must be consumed by the referencing app should be public; internal members are not visible across the assembly boundary.
• `#:ref` is transitive: a referenced file can contain its own `#:ref` and other `#:` directives.
• Relative paths are resolved relative to the file containing the directive.
• Some SDK builds require `#:property ExperimentalFileBasedProgramEnableRefDirective=true`; remove that property if the SDK accepts `#:ref` without it.

`#:sdk` — SDK selection

Override the default SDK (`Microsoft.NET.Sdk`):

#:sdk Microsoft.NET.Sdk.Web

`#:include` and `#:exclude` — Multi-file apps

In .NET SDK 10.0.300 and later, file-based apps can include additional files in the same virtual project. Check the full `dotnet --version` output before using these directives; a 10.0.100 or 10.0.200 SDK is still .NET 10 but does not support them. Use `#:include` for helper source files and supported assets, and `#:exclude` to remove files from an include pattern or default item set.

#!/usr/bin/env dotnet
#:include H