Starting with C# used to mean creating projects, writing boilerplate code, and understanding concepts like namespaces and classes before you could even print “Hello World”.

With .NET 10, you can now run C# code from a single file, just like Python or JavaScript.

In this guide, you’ll run your first file-based app and learn how to add packages, properties, and project references when you need them.

The Old Way (And Why It Was Frustrating)

Remember the classic way to write a C# program? Even the simplest “Hello World” needed all of this:

using System;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
}

That’s 11 lines just to print one message. And that’s not all - you also needed:

  • A .csproj project file with XML configuration
  • bin/ and obj/ folders cluttering your directory
  • Often appsettings.json for configuration
  • Properties/launchSettings.json for debug settings

All this ceremony before writing a single line of actual logic. For beginners, this was overwhelming.

The New Way

Now, here’s the same program in .NET 10:

Console.WriteLine("Hello World!");

That’s it. One line. No namespace, no class, no Main method.

To run it, open your terminal and type:

dotnet hello.cs

No project file needed. The SDK builds behind the scenes the first time you run it.

If you’re in a directory that already has a .csproj, use dotnet run --file hello.cs to make sure the file-based app runs.

Try It Yourself

Let’s create your first file-based app in 5 simple steps.

Step 1: Get the Tools

Ensure you have the .NET 10 SDK installed and grab your favorite text editor (VS Code, Notepad, etc.).

Step 2: Create a File

Create a new file called hello.cs.

Step 3: Write the Code

Add this simple C# code to your file:

Console.WriteLine("Hello! What's your name?");
var name = Console.ReadLine();
Console.WriteLine($"Nice to meet you, {name}!");

Step 4: Open Your Terminal

Open your terminal or command prompt.

Step 5: Run the App

Run the file using the dotnet command:

dotnet hello.cs

You should see something like:

Hello! What's your name?
> Max
Nice to meet you, Max!

And that’s it - you just ran C# without creating a project.

Adding Power with Directives

File-based apps aren’t limited to simple scripts. You can add NuGet packages, set MSBuild properties, and reference full projects. All you need are directives at the top of your file.

Add NuGet packages

Want to use a NuGet package? Just add a #:package directive:

#:package Humanizer@2.14.1

using Humanizer;

Console.WriteLine(DateTime.Now.AddHours(-2).Humanize()); // "2 hours ago"
Console.WriteLine(1000000.ToWords());                    // "one million"

Run it with dotnet myscript.cs and the package gets restored automatically.

Set build properties

Need to target a specific framework or enable nullable references? Use #:property:

#:property Nullable=enable
#:property WarningLevel=5

string? name = null;
Console.WriteLine(name?.ToUpper() ?? "No name provided");

Note: File-based apps enable native AOT publishing by default. If you need to disable that, set:

#:property PublishAot=false

Reference projects

You can even reference existing .csproj files:

#:project ../MyLibrary/MyLibrary.csproj

var result = MyLibrary.Calculator.Add(5, 3);
Console.WriteLine(result);

This is great for testing libraries or building quick tools that use your existing code.

Choose an SDK

By default, file-based apps use the standard Microsoft.NET.Sdk. But what if you want to build a quick web API or a background worker? Use the #:sdk directive:

#:sdk Microsoft.NET.Sdk.Web

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

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

app.Run();

Run it with dotnet webapi.cs and you’ve got a minimal API running - no project file needed.

Available SDKs:

  • Microsoft.NET.Sdk - Console apps (default)
  • Microsoft.NET.Sdk.Web - Web apps and APIs
  • Microsoft.NET.Sdk.Worker - Background services
  • and more as .NET evolves!

Launch profiles

File-based apps support launch profiles via a flat file named after your app. For example, if your file is myapp.cs, you can add myapp.run.json next to it.

App configuration

Need configuration? File-based apps follow the same naming convention. Use myapp.settings.json or myapp.settings.Development.json (matching your .cs filename) instead of the standard appsettings.json.

Convert to a full project

Started with a simple script but now it’s growing? You can convert your file-based app into a full project:

dotnet project convert myscript.cs

This creates a proper .csproj file with equivalent package references and properties derived from your directives. Perfect when your script evolves into something bigger.

Build Something Useful

Let’s make something practical: a tool that counts files in any folder you specify.

Create a file called filecount.cs:

if (args.Length == 0)
{
    Console.WriteLine("Usage: dotnet filecount.cs <folder>");
    return;
}

var folder = args[0];

if (!Directory.Exists(folder))
{
    Console.WriteLine($"Folder not found: {folder}");
    return;
}

var files = Directory.GetFiles(folder);
Console.WriteLine($"Found {files.Length} files in {folder}");

Run it with a folder path:

dotnet filecount.cs ./Documents

Output:

Found 42 files in ./Documents

What’s happening here?

  • args contains any values you pass after the filename
  • Directory.Exists() checks if a folder exists
  • Directory.GetFiles() returns all files in a folder

You just built a real command-line tool in under 15 lines.

What’s Next?

File-based apps are perfect for:

  • Learning C#: focus on code, not project setup
  • Quick scripts: automate tasks without all the ceremony
  • Prototyping: test ideas fast
  • Testing & Benchmarking: quickly test code snippets or run performance benchmarks
  • Polyglot Aspire: check out aspire.dev for more on using file-based apps with Aspire

When should you use a full project instead?

  • Your app needs multiple files
  • You’re working with a team
  • You need to write tests

Looking ahead: Future .NET versions are expected to bring proper multi-file support for file-based apps, making them even more useful for larger scripts.

Resources

Wrapping Up

File-based apps make C# as approachable as any scripting language. No more boilerplate getting in your way. Just write code and run it with dotnet yourfile.cs.

Give it a try and see how simple C# can be!