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.

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:
- One file: run C# without a project
- #:include: split the app into files
- Nested includes: a file that includes other files
- Settings: read a JSON file, and watch it crash
- 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
-
dotnet run app.csruns a C# file without a project. -
#:include path.csadds another file (.NET 11). - Included files can include other files. Only the entry file has top-level code.
-
EntryPointFileDirectoryPathgives you the folder of your app file. - AOT is on by default: use
#:property PublishAot=falseor the JSON source generator.
Would you use this for small tools, or stay with projects? Tell me in comments. 🙂


