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. 🙂

Leave a Reply