Building File-Based Apps in .NET: A Complete Guide With Multi-File Support

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!

---

👉 Read original article on my newsletter: https://antondevtips.com/blog/building-file-based-apps-in-dotnet-with-multi-file-support

What Are File-Based Apps in .NET

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:

dotnet 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:

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

Then run it:

dotnet 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

Adding NuGet Packages and SDKs with Directives

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:

#:package Newtonsoft.Json@13.0.3

using Newtonsoft.Json;

var data = new { Name = "Anton", Year = 2026 };
var json = JsonConvert.SerializeObject(data, Formatting.Indented);
Console.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:

#:sdk Microsoft.NET.Sdk.Web

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.MapGet("/", () => "Hello from a single-file API!");

app.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:

#:project ../MyLibrary/MyLibrary.csproj

using MyLibrary;

var calculator = new Calculator();
Console.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.

---

👉 Read original article on my newsletter: https://antondevtips.com/blog/building-file-based-apps-in-dotnet-with-multi-file-support