Single file C# Applications are Here!

-

In .NET 10, Microsoft introduced one of the most exciting quality-of-life features C# has seen in years: file-based apps.
If you’ve ever wished C# development felt more like Python—instant scripts, no boilerplate, no projects—this new model was built for you.

File-based apps let you write a single .cs file, run it immediately with dotnet run, and skip the ceremony of projects, folders, .csproj files, and startup templates. It’s C#, but with a scripting-first mindset.

In this article, we’ll break down:

  • What file-based apps are

  • Why Microsoft built them

  • How they help onboard developers faster

  • How they compete with Python-style scripting workflows

  • How to use packages, properties, and project metadata

  • Limitations of file-based apps

  • How to make them executable on macOS and Linux

  • Step-by-step setup and examples

What Are File-Based Apps?

File-based apps are standalone C# programs written entirely in a single file, without needing:

  • A csproj

  • A project folder structure

  • A Program.cs

  • Using statements (in many cases)

  • Startup boilerplate

If you've used languages like Python, Ruby, or Bash, the experience will feel familiar:

    Console.WriteLine("Hello, World!");

Run it:

    dotnet run hello.cs

That’s it.

They Are Real C# Programs

Under the hood, the .NET SDK dynamically creates a project in memory, compiles your file, and executes it. You still get strong typing, async/await, LINQ, and full NuGet support.

Why File-Based Apps Were Designed

1. Easier Onboarding for New Developers

The traditional .NET project system creates unnecessary friction. File-based apps remove all barriers to printing your first “Hello, World.”

2. Competing with Python

Python dominates scripting because it is frictionless. File-based apps allow C# to compete directly with:

  • CLI utilities

  • Quick scripts

  • Prototyping

  • DevOps automation

  • Teaching and training

3. A True Scripting Mode for C#

Sometimes you want:

  • LINQ

  • Strong typing

  • Clean debugging

  • NuGet

  • Modern language features

File-based apps deliver that without projects or ceremony.

Requirements

To use file-based apps, you’ll need:

✔ .NET 10 SDK

https://dotnet.microsoft.com

✔ VS Code (Required)

❌ Visual Studio — not supported
❌ Rider — not supported
✔ VS Code — supported

✔ Enable File-Based App Support

Install the C# Dev Kit extension
Turn on experimental features if prompted.

Get Started (Step-by-Step)

1. Create a global.json file

    {
      "sdk": {
        "version": "10.0.100"
      }
    }

2. Create Your First File

filebaseapp.cs

    Console.WriteLine("Hello, World!");

3. Run It

    dotnet run filebaseapp.cs

4. Output

    Hello, World

Using Packages in File-Based Apps

File-based apps support three special directives:

DirectivePurpose
#:packageAdd NuGet packages
#:propertySet compiler or project properties
#:projectDefine project metadata

Adding a NuGet Package

    #:package Newtonsoft.Json

    using Newtonsoft.Json;

    var json = JsonConvert.SerializeObject(new { Name = "David" });
    Console.WriteLine(json);

Run:

    dotnet run myscript.cs

NuGet is resolved automatically.

Setting a Compile Property

    #:property Nullable=enable

Or:

    #:property AllowUnsafeBlocks=true

Project Metadata

    #:project MyCommonLib ..//Full Path to your MyCommonLib.csproj

Making File-Based Apps Executable (Linux / macOS)

You can run your .cs file like a script.

1. Add a Shebang

    #!/usr/bin/env dotnet-run
    Console.WriteLine("Hello from Linux!");

2. Make It Executable

    chmod +x myscript.cs

3. Run It

    ./myscript.cs

Limitations of File-Based Apps

🚫 1. Single-file only

No multi-file splitting (yet).

🚫 2. Limited IDE support

Only VS Code works right now.

🚫 3. No full project system

No .csproj, no custom targets, no build pipelines.

🚫 4. Not for large apps

Great for scripts, tools, demos—not enterprise systems.

🚫 5. First-run compilation overhead

The SDK dynamically generates a project during execution.

When Should You Use File-Based Apps?

Great For:

  • Quick utilities

  • DevOps scripts

  • AI-assisted coding demos

  • Teaching C#

  • Rapid prototyping

  • Small automation tasks

  • Replacing Python scripts

  • Lunch-and-learn demos

Not Great For:

  • Multi-layer applications

  • Web APIs

  • Blazor apps

  • Enterprise systems

Think of them as C# micro-scripts.

Real Example: Developer Code Metrics Script

    #:package Microsoft.CodeAnalysis.CSharp

    using Microsoft.CodeAnalysis;
    using Microsoft.CodeAnalysis.CSharp;

    var file = args[0];
    var code = await File.ReadAllTextAsync(file);

    var tree = CSharpSyntaxTree.ParseText(code);
    var root = tree.GetCompilationUnitRoot();

    Console.WriteLine($"Lines: {code.Split('\n').Length}");
    Console.WriteLine($"Classes: 
            {root.DescendantNodes().OfType<ClassDeclarationSyntax>().Count()}");

Run:

    dotnet run metrics.cs MyFile.cs

You now have a Roslyn-powered tool in one file.

Conclusion

File-based apps are one of the smoothest improvements .NET has introduced in years. They make C#:

  • Lightweight

  • Fast

  • Scriptable

  • Easy to teach

  • Competitive with Python

  • AI-friendly

Whether you’re onboarding new developers, automating your workflow, or building quick tools, file-based apps bring a new level of simplicity to the .NET ecosystem.


[source code]

Comments

Post a Comment

Popular posts from this blog

Yes, Blazor Server can scale!

-
Image
From the very beginning of the release of Blazor Server naysayers have incorrectly stated that Blazor Server can not scale.  They usually state that the limit is 5,000 concurrent users. There are several misconceptions and wrong assumptions about their statement.  Let's break it down and get a better understanding of Blazor server-side scaling. What is the "limit" for users When Microsoft talks about the need to scale an application, what they are saying is that when a normal response for any concurrent user is taking longer than 200 ms, the system is not performant and needs to scale. We will accept that definition: If any normal user response is taking longer than 200 ms, the system needs to scale for concurrent users. By a normal response, we are referring to a page get, a post, etc.  Large database access requests would not be included in this measurement. What is scaling There are 2 common ways to scale, scale, out horizontally, and scale-up, up vertically. In our di...
Read more

Offline-First Strategy with Blazor PWAs: A Complete Guide 🚀

-
Image
One of the most powerful features of Progressive Web Apps (PWAs) is their ability to function seamlessly even when offline. For users, this means uninterrupted access to critical features regardless of network conditions. For developers, adopting an offline-first strategy ensures a robust, user-friendly experience while aligning with modern web development best practices. Blazor, Microsoft’s modern web framework, simplifies building PWAs with offline capabilities by leveraging features like service workers, caching, and IndexedDB. In this guide, we’ll dive into how you can implement an offline-first strategy in your Blazor PWA. Why Offline-First Matters An offline-first strategy doesn’t just improve user experience—it also provides: Reliability : Apps remain functional even with intermittent or no connectivity. Performance : Cached assets load faster, improving responsiveness. Engagement : Users can interact with the app at any time, enhancing retention and trust. Key Components of Of...
Read more

Customizing PWA Manifest and Icons for a Polished User Experience 🚀

-
Image
  Progressive Web Apps (PWAs) blur the line between web and native applications, offering a seamless and engaging user experience. But to make your PWA truly stand out, it’s essential to customize its manifest file and design professional-grade icons and splash screens . These elements influence how users perceive your app and ensure it looks and feels like a polished, high-quality product. In this guide, we’ll explore how to tailor the manifest.json file and create stunning icons and splash screens to deliver a professional and consistent user experience. What is the PWA Manifest File? The manifest.json file is a JSON file that provides metadata about your PWA. It defines how your app appears to users and controls its behavior when installed on a device. Key properties include: Name and description : How your app is displayed to users. Icons : App icons in various sizes. Theme and background colors : Define the app's look and feel. Display mode : Controls whether the app appear...
Read more