Since .NET 10 you can run a C# file without a project: dotnet run app.cs. No .sln, no .csproj. But it was one file only. In .NET 11 a file-based app can have many files, and that makes it useful for real small tools.

I tried it on the classic Mars Rover kata. A rover starts at 0 0 N. L and R turn 90°, M moves one cell forward. The program prints the final position.

NASA's Perseverance rover on Mars, taking a selfie with the Ingenuity helicopter in the background.
The real Mars rover: Perseverance, with the Ingenuity helicopter behind it. Ours only knows L, R and M. Credit: NASA/JPL-Caltech/MSSS

Here is what we'll go through:

  1. One file: run C# without a project
  2. #:include: split the app into files
  3. Nested includes: a file that includes other files
  4. Settings: read a JSON file, and watch it crash
  5. Native AOT: turn it off, or use the JSON source generator

1. One file: run C# without a project

// app.cs Console.WriteLine("Rover is ready"); 
dotnet run app.cs 

That's all. The SDK creates a hidden project for you.

2. #:include: split the app into files

Move the rover logic to its own file, and include it from app.cs:

mars-rover/ ├── app.cs ├── settings.json ├── rover/rover.cs └── helpers/directions.cs 
// app.cs #:include rover/rover.cs var rover = new Rover(0, 0, "N"); rover.Execute("LMLMLMLMM"); Console.WriteLine(rover); // 0 1 N 

One rule: only the entry file (app.cs) can have top-level statements. Included files only add types.

3. Nested includes: a file that includes other files

The rover includes the directions helper itself, so app.cs doesn't need to know about it:

// rover/rover.cs #:include ../helpers/directions.cs class Rover(int x, int y, string facing) { int _x = x, _y = y; int _dir = Directions.IndexOf(facing); public void Execute(string commands) { foreach (var c in commands) { switch (c) { case 'L': _dir = Directions.Left(_dir); break; case 'R': _dir = Directions.Right(_dir); break; case 'M': var (dx, dy) = Directions.Delta(_dir); _x += dx; _y += dy; break; default: throw new ArgumentException($"Unknown command: {c}"); } } } public override string ToString() => $"{_x} {_y} {Directions.Name(_dir)}"; } 
// helpers/directions.cs static class Directions { const string Ring = "NESW"; // clockwise static readonly (int, int)[] Deltas = [(0, 1), (1, 0), (0, -1), (-1, 0)]; public static int IndexOf(string f) => Ring.IndexOf(f) is var i and >= 0 && f.Length == 1 ? i : throw new ArgumentException($"Unknown direction: {f}"); public static int Left(int d) => (d + 3) % 4; public static int Right(int d) => (d + 1) % 4; public static (int, int) Delta(int d) => Deltas[d]; public static char Name(int d) => Ring[d]; } 

Each file says what it needs, like a using, but for files.

4. Settings: read a JSON file, and watch it crash

Put the start position in settings.json:

{ "X": 0, "Y": 0, "Facing": "N" } 

Read it from the folder of app.cs, so it works wherever you run the app from:

var dir = AppContext.GetData("EntryPointFileDirectoryPath") as string ?? "."; var json = File.ReadAllText(Path.Combine(dir, "settings.json")); var start = JsonSerializer.Deserialize<Start>(json)!; record Start(int X, int Y, string Facing); 

Run it, and it crashes:

System.InvalidOperationException: Reflection-based serialization has been disabled for this application. 

5. Native AOT: turn it off, or use the JSON source generator

File-based apps have Native AOT on by default, and AOT turns off reflection-based JSON. You have two options.

Option A: turn AOT off. Add one line at the top, and the code from step 4 works as is:

#:property PublishAot=false 

Option B: keep AOT, use the JSON source generator. A few more lines, but you keep the fast startup and the native binary:

#!/usr/bin/env dotnet #:include rover/rover.cs using System.Text.Json; using System.Text.Json.Serialization; var dir = AppContext.GetData("EntryPointFileDirectoryPath") as string ?? "."; var json = File.ReadAllText(Path.Combine(dir, "settings.json")); var start = JsonSerializer.Deserialize(json, AppJson.Default.Start)!; var rover = new Rover(start.X, start.Y, start.Facing); rover.Execute(args.Length > 0 ? args[0] : "LMLMLMLMM"); Console.WriteLine(rover); record Start(int X, int Y, string Facing); [JsonSerializable(typeof(Start))] partial class AppJson : JsonSerializerContext; 
$ dotnet run app.cs 0 1 N $ dotnet run app.cs -- RRMMLM 1 -2 E 

For a quick tool, A is fine. If startup time matters, choose B. The #! line on top removes analyzer warning CA2266, and on macOS/Linux it lets you run chmod +x app.cs && ./app.cs.

Notes for later

  1. dotnet run app.cs runs a C# file without a project.
  2. #:include path.cs adds another file (.NET 11).
  3. Included files can include other files. Only the entry file has top-level code.
  4. EntryPointFileDirectoryPath gives you the folder of your app file.
  5. AOT is on by default: use #:property PublishAot=false or the JSON source generator.

Would you use this for small tools, or stay with projects? Tell me in comments. 🙂