For years, even the smallest C# program required a solution file, a project file, and a folder structure. While Python and JavaScript developers could create a single file and run it in seconds, .NET developers had to create a solution and add a csproj file just to test an idea.

That changed with .NET 10, which introduced file-based apps. Now you can run a C# file directly with dotnet run.

And in April 2026 in .NET 11 Preview 3 we received a support for using multiple files in file-based apps with the #:include directive.

This finally makes C# a real option for scripts, automation, internal tooling, and quick prototypes - without the overhead of a full project.

In this post, we will explore:

• What Are File-Based Apps in .NET
• Adding NuGet Packages and SDKs with Directives
• Splitting File-Based Apps Across Multiple Files
• Building an HTTP Health-Check Tool
• Building a Minimal API with EF Core and SQLite
• Converting a File-Based App to a Full Project

Let's dive in!

Traditionally, every C# application required three things:

• Solution file (*.sln)
• Project file (*.csproj)
• Source code (*.cs).

Even for a 10-line script, you had to create a new solution, add a project with dotnet new console, wait for the scaffolding to finish, and only then write your actual code.

Starting with .NET 10, you can skip all of that. You can create a single .cs file and run it directly:

bash
1dotnet run main.cs

That's it. No project file. No solution file. Just one file.

This puts C# on equal footing with Python, JavaScript, Node.js, and other scripting languages. For CLI utilities, automation tasks, and one-off tools, this completely changes the workflow.

Let's see the simplest possible example. Create a file called hello.cs:

csharp
1Console.WriteLine("Hello from a file-based app!");
2Console.WriteLine($"Today is {DateTime.Now:dddd, MMMM d, yyyy}");

Then run it:

bash
1dotnet run hello.cs

Notice there is no Main method, no class Program, no using statement. File-based apps build on top of top-level statements (introduced in C# 9) and implicit usings, so you can write code as if you were in a script.

Behind the scenes, the .NET CLI compiles your file in a temporary location and runs the resulting binary. The first run takes a moment, but subsequent runs are cached and fast.

I've used this many times in the last year for small tasks I would have otherwise written in Python (or created a solution project):

• Quick data transformations on JSON or CSV files
• Calling internal APIs to verify a deployment
• Running test scripts
• Parsing log files to extract patterns

A real script usually needs more than the BCL. You probably want JSON parsing, HTTP calls, or database access.

File-based apps support special # directives at the top of your file to declare dependencies.

The #:package Directive

Use #:package to reference any NuGet package:

csharp
1#:package [email protected]
2
3using Newtonsoft.Json;
4
5var data = new { Name = "Anton", Year = 2026 };
6var json = JsonConvert.SerializeObject(data, Formatting.Indented);
7Console.WriteLine(json);

The format is #:package PackageName@Version. The .NET CLI restores the package on first run, just like it would for a regular project.

The #:sdk Directive

Use #:sdk when you need a specific SDK, such as the Web SDK for ASP.NET Core:

csharp
1#:sdk Microsoft.NET.Sdk.Web
2
3var builder = WebApplication.CreateBuilder();
4var app = builder.Build();
5
6app.MapGet("/", () => "Hello from a single-file API!");
7
8app.Run();

By default, file-based apps use Microsoft.NET.Sdk (the standard SDK). Switching to Microsoft.NET.Sdk.Web unlocks ASP.NET Core types like WebApplication without any project setup.

The #:project Directive

If you need to call into an existing project (for example, a shared class library), use #:project:

csharp
1#:project ../MyLibrary/MyLibrary.csproj
2
3using MyLibrary;
4
5var calculator = new Calculator();
6Console.WriteLine(calculator.Add(2, 3));

This is helpful when you have a class library and want to write a quick tool that uses it, without creating yet another console project.

In .NET 10, file-based apps had one significant limitation: everything had to fit in a single file. That worked for short scripts, but the file grew too big for anything larger.

.NET 11 Preview 3 fixes this with the #:include directive.

You can now split your code across multiple files while keeping the file-based workflow.

Imagine you are writing a small data processor. In .NET 10, you had to put models, helpers, and the main logic all in one file. Now you can split it cleanly:

csharp
1// models.cs
2public record Customer(int Id, string Name, string Email);

csharp
1// helpers.cs
2public static class Helpers
3{
4    public static string Format(Customer c) =>
5        $"[{c.Id}] {c.Name} <{c.Email}>";
6}

csharp
1// main.cs
2#:include models.cs
3#:include helpers.cs
4
5var customer = new Customer(1, "John Doe", "[email protected]");
6Console.WriteLine(Helpers.Format(customer));

Run it the same way as before:

bash
1dotnet run main.cs

The #:include directive tells the compiler to include the referenced file in the compilation. You can include as many files as you need, and they can live in subfolders:

csharp
1#:include models/customer.cs
2#:include models/order.cs
3#:include services/email-service.cs

Roslyn also adds editor IntelliSense for the directive, so completion works when you type #:include in your main file.

This completes the file-based apps feature. You can start with a single file, grow it into multiple files as your script matures, and convert it to a full project only when you truly need one.

Let's build something practical: a tool that monitors a list of URLs every 5 seconds and reports their status.

This is the kind of small utility that's perfect for a file-based app.

We'll split it into two files: one for the health-check logic, and one for the entry point.

The Health-Check Logic

Create healthchecker.cs with the class that performs the actual check:

csharp
1using System.Diagnostics;
2
3public sealed class HealthChecker(HttpClient httpClient)
4{
5    public async Task<HealthCheckResult> CheckAsync(string url)
6    {
7        var sw = Stopwatch.StartNew();
8
9        try
10        {
11            using var response = await httpClient.GetAsync(url);
12            sw.Stop();
13
14            return new HealthCheckResult(
15                Url: url,
16                StatusCode: (int)response.StatusCode,
17                IsHealthy: response.IsSuccessStatusCode,
18                ResponseTimeMs: sw.ElapsedMilliseconds);
19        }
20        catch (Exception ex)
21        {
22            sw.Stop();
23
24            return new HealthCheckResult(
25                Url: url,
26                StatusCode: 0,
27                IsHealthy: false,
28                ResponseTimeMs: sw.ElapsedMilliseconds,
29                Error: ex.Message);
30        }
31    }
32}
33
34public record HealthCheckResult(
35    string Url,
36    int StatusCode,
37    bool IsHealthy,
38    long ResponseTimeMs,
39    string? Error = null);

The HealthChecker class takes an HttpClient and exposes a single CheckAsync method. It captures the response time, status code, and any exception that occurs.

The Entry Point

Create main.cs with the URLs to monitor and the polling loop:

csharp
1#:include healthchecker.cs
2
3var urls = new[]
4{
5    "https://github.com",
6    "https://example.com"
7};
8
9using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(5) };
10var checker = new HealthChecker(http);
11
12Console.WriteLine($"Monitoring {urls.Length} URLs every 5 seconds. Press Ctrl+C to stop.");
13Console.WriteLine();
14
15while (true)
16{
17    foreach (var url in urls)
18    {
19        var result = await checker.CheckAsync(url);
20        var status = result.IsHealthy ? "OK  " : "FAIL";
21        var error = result.Error is null ? "" : $" - {result.Error}";
22
23        Console.WriteLine(
24            $"[{DateTime.Now:HH:mm:ss}] {status} {result.StatusCode} " +
25            $"{result.Url} ({result.ResponseTimeMs}ms){error}");
26    }
27
28    Console.WriteLine();
29    await Task.Delay(TimeSpan.FromSeconds(5));
30}

The main file pulls in healthchecker.cs with #:include and runs an infinite loop that checks each URL every 5 seconds.

To run the app, execute the following command at the main file:

bash
1dotnet run main.cs

You'll see output like this:

1Monitoring 3 URLs every 5 seconds. Press Ctrl+C to stop.
2
3[14:32:01] OK   200 https://github.com (412ms)
4[14:32:02] OK   200 https://example.com (89ms)
5
6[14:32:07] OK   200 https://github.com (398ms)
7[14:32:07] OK   200 https://example.com (76ms)

Now let's go further. We'll build an Orders API with EF Core and SQLite, all as a file-based app.

This is a real, runnable web API that you could use for prototyping or internal tooling. But the entire thing is just three files without a project.

We'll structure it like this:

• main.cs - DI setup and the Minimal API endpoints
• OrdersDbContext.cs - the EF Core DbContext with mappings
• Order.cs - the Order entity

Create Order.cs with the entity model:

csharp
1public class Order
2{
3    public int Id { get; set; }
4    public string OrderNumber { get; set; } = string.Empty;
5    public string CustomerName { get; set; } = string.Empty;
6    public decimal Amount { get; set; }
7    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
8}

Create OrdersDbContext.cs with the EF Core context and inline Fluent API mappings:

csharp
1using Microsoft.EntityFrameworkCore;
2
3public class OrdersDbContext : DbContext
4{
5    public OrdersDbContext(DbContextOptions<OrdersDbContext> options)
6        : base(options) { }
7
8    public DbSet<Order> Orders => Set<Order>();
9
10    protected override void OnModelCreating(ModelBuilder modelBuilder)
11    {
12        modelBuilder.Entity<Order>(entity =>
13        {
14            entity.ToTable("Orders");
15            entity.HasKey(o => o.Id);
16
17            entity.Property(o => o.OrderNumber)
18                .HasMaxLength(50)
19                .IsRequired();
20
21            entity.Property(o => o.CustomerName)
22                .HasMaxLength(200)
23                .IsRequired();
24
25            entity.Property(o => o.Amount)
26                .HasColumnType("decimal(18,2)");
27
28            entity.HasIndex(o => o.OrderNumber).IsUnique();
29        });
30    }
31}

The mappings live directly inside OnModelCreating for simplicity. For larger projects, you would extract them into separate IEntityTypeConfiguration<T> classes - but for a file-based app, inline mappings are perfect.

Now the entry point. Create main.cs with the SDK directive, package directive, includes, DI setup, and the API endpoints:

csharp
1#:sdk Microsoft.NET.Sdk.Web
2#:package [email protected]
3#:include Order.cs
4#:include OrdersDbContext.cs
5
6using Microsoft.EntityFrameworkCore;
7
8var builder = WebApplication.CreateBuilder();
9
10builder.Services.AddDbContext<OrdersDbContext>(options =>
11    options.UseSqlite("Data Source=orders.db"));
12
13var app = builder.Build();
14
15// Make sure the database and table exist before handling requests
16using (var scope = app.Services.CreateScope())
17{
18    var db = scope.ServiceProvider.GetRequiredService<OrdersDbContext>();
19    await db.Database.MigrateAsync();
20}
21
22app.MapGet("/orders", async (OrdersDbContext db) =>
23    await db.Orders.AsNoTracking().ToListAsync());
24
25app.MapGet("/orders/{id:int}", async (int id, OrdersDbContext db) =>
26    await db.Orders.FindAsync(id) is { } order
27        ? Results.Ok(order)
28        : Results.NotFound());
29
30app.MapPost("/orders", async (Order order, OrdersDbContext db) =>
31{
32    db.Orders.Add(order);
33    await db.SaveChangesAsync();
34    return Results.Created($"/orders/{order.Id}", order);
35});
36
37app.MapDelete("/orders/{id:int}", async (int id, OrdersDbContext db) =>
38{
39    var order = await db.Orders.FindAsync(id);
40    if (order is null) return Results.NotFound();
41
42    db.Orders.Remove(order);
43    await db.SaveChangesAsync();
44    return Results.NoContent();
45});
46
47app.Run();

Look at the top of the file. There's a lot going on in just four lines:

• #:sdk Microsoft.NET.Sdk.Web switches to the web SDK so we can use WebApplication
• #:package [email protected] pulls in the SQLite provider
• #:include Order.cs brings the entity into the compilation
• #:include OrdersDbContext.cs brings the DbContext into the compilation

Everything below is standard ASP.NET Core code.

Run the API:

bash
1dotnet run main.cs

The first run takes a few seconds while NuGet restores EF Core and the SQLite provider. Subsequent runs are fast.

You can now hit the endpoints with curl:

bash
1curl -X POST http://localhost:5000/orders \
2    -H "Content-Type: application/json" \
3    -d '{"orderNumber":"ORD-001","customerName":"Alice","amount":99.99}'
4
5curl http://localhost:5000/orders

A working web API with a real database, in three files, with no project setup. That's the power of multi-file file-based apps.

There comes a point when a file-based app is no longer enough. Maybe you need multiple projects, complex build steps, or proper packaging for distribution.

You can use the .NET CLI to convert your file-based app into a regular project with a single command:

bash
1dotnet project convert main.cs

What You Get

The command creates a new folder next to your file (named after your main file) containing a regular project structure:

1main/
2├── main.csproj
3├── Order.cs
4├── OrdersDbContext.cs
5└── main.cs

The csproj file includes the SDK and package references declared with #: directives in your script. The #:include directives are removed because all files are now part of the project naturally. Your main.cs becomes a standard top-level statements file.

You can then open the folder in your IDE and continue working as if you had created the project from scratch.

When to Convert

File-based apps are great until they're not. Convert to a full project when:

• You need multiple projects in one solution - for example, splitting a Web API and a class library
• You need MSBuild customizations - custom targets, conditional compilation, build properties
• You need proper packaging - publishing as a NuGet package or a self-contained executable
• You need CI/CD with custom steps - pipelines tend to assume a project file exists
• The team grows - working with csproj is more familiar to most .NET developers
• You need test projects - unit tests work best in a multi-project solution structure

The good news is that you don't have to decide upfront. Start as a file-based app, grow it as needed, and convert only when you exceed the file-based approach.

File-based apps are the most useful productivity feature .NET has shipped in years.

What started in .NET 10 as a single-file workflow becomes a real, scalable approach in .NET 11 Preview 3 with multi-file support.

When to use file-based apps:

• Quick scripts, prototypes, and proof-of-concept work
• CLI tools and automation utilities
• Internal tooling that doesn't need a full project structure
• Demos and learning material where setup gets in the way
• Glue code that calls existing libraries or APIs

When to use full projects:

• Production applications that need long-term maintenance
• Solutions with multiple projects (libraries, APIs, tests)
• Anything that requires custom MSBuild logic or packaging
• Code that needs to be distributed as a NuGet package

I've already replaced several Python utility scripts with file-based C# apps in my own toolbox. The strong typing, IntelliSense, and ability to share code with my main projects make them genuinely better tools.

Are you using file-based apps yet? Stay subscribed to my newsletter for more practical .NET content like this.

Hope you find this newsletter useful. See you next time.