dotnet-file-based-apps

# .NET File-Based Apps

File-based apps let you build, run, and publish .NET applications from a single C# file without a `.csproj`. Requires .NET 10 SDK or later.

## Quick Start

Create a single `.cs` file with directives at the top:

```csharp
#:package Spectre.Console@*

using Spectre.Console;

AnsiConsole.MarkupLine("[green]Hello, World![/]");
```

Run it:

```bash
dotnet run file.cs
# or shorthand:
dotnet file.cs
```

## Directives

Place at the top of your C# file, prefixed with `#:`:

| Directive | Purpose | Example |
|-----------|---------|---------|
| `#:package` | Add NuGet package | `#:package Newtonsoft.Json@13.0.3` |
| `#:project` | Reference another project | `#:project ../Shared/Shared.csproj` |
| `#:property` | Set MSBuild property | `#:property TargetFramework=net10.0` |
| `#:sdk` | Specify SDK (default: `Microsoft.NET.Sdk`) | `#:sdk Microsoft.NET.Sdk.Web` |

**Package versions**: Always specify version (`@3.1.1`) or use `@*` for latest. Omitting version only works with central package management.

## CLI Commands

```bash
dotnet run file.cs              # Run
dotnet run file.cs -- arg1 arg2 # Run with arguments
dotnet build file.cs            # Build
dotnet publish file.cs          # Publish (AOT by default)
dotnet pack file.cs             # Package as .NET tool
dotnet clean file.cs            # Clean build outputs
dotnet restore file.cs          # Restore packages
dotnet project convert file.cs  # Convert to traditional project
```

## Native AOT

**Enabled by default.** File-based apps produce optimized, self-contained executables with native AOT. This means:

- Faster startup and smaller memory footprint
- All code must be AOT-compatible (no reflection-based serialization, etc.)
- Use source generators for JSON serialization (see examples below)

To disable:

```csharp
#:property PublishAot=false
```

## Shell Execution (Unix)

Add shebang and make executable:

```csharp
#!/usr/bin/env dotnet
#:package Spectre.Console@*

using Spectre.Console;