Running a C# code file without a project file

As you have seen in this chapter, as well as .cs code files, C# projects usually need a project file. The project file configures which version of the .NET Runtime you want to target, language features like nullability and global namespace imports, and references to other projects and packages.

However, when you are first learning a programming language, you probably won’t change many of those options, so it’s extra complexity without any benefit.

Rival languages like Python allow you to execute a code file without a project file, as shown in the following code:

python app.py

Introducing file-based apps

C# 14 introduces a similar feature named file-based apps that allows developers to execute single .cs files directly, as shown in the following command:

dotnet run app.cs

Microsoft’s official terms are “file-based app” versus “project-based app.” This new feature is also sometimes referred to as “dotnet run app.cs,” which is misleading because you can actually miss out the “run” part of the command!

This enhancement supports top-level statements, allowing for concise code without boilerplate, and simplifies the development process by eliminating the need for a full project structure, making C# more accessible for quick scripting and prototyping.

The benefits of being able to execute a single .cs file include easier prototyping, ideal for quick tests and learning, where you can quickly experiment with ideas without overhead, and a lower barrier to entry for newcomers to C#.

The filename of the C# file does not have to be Program.cs.

Creating a file-based app

File-based apps are not supported in Visual Studio because it’s a command-line feature.

Let’s see an example:

1. In the Chapter01 directory, create a new directory named NoProject.
2. In the NoProject directory, use a plain text editor to create a file named hello.cs, with content as shown in the following code:

   Console.WriteLine("Hello World with no project file!");
   

3. At the command prompt or terminal, in the NoProject folder, use the dotnet CLI to run the hello.cs file, as shown in the following code:

   dotnet run hello.cs
   

4. Note the result, as shown in the following output:

   Hello World with no project file!
   

Currently, you can only have one C# file in a file-based app. Multi-file support is planned for .NET 11.

Configuring no-project C# code files

To enhance functionality, you can use special #: directives at the top of the .cs file:

• You can add NuGet package references like Humanizer, as shown in the following code:

  #:package Humanizer@2.14.1
  using Humanizer;
  Console.WriteLine(TimeSpan.FromDays(1).Humanize());
  

• You can add project references, as shown in the following code:

  #:project ../MyClassLib/MyClassLib.csproj
  

• You can specify the SDK, like switching to Microsoft.NET.Sdk.Web for ASP.NET Core projects, as shown in the following code:

  #:sdk Microsoft.NET.Sdk.Web
  

To separate the SDK ID and an explicit version number, use an @, for example, #:sdk Aspire.AppHost.Sdk@9.5.0.

• You can set MS Build properties, like setting the C# language version to preview, as shown in the following code:

  #:property LangVersion=preview
  

• On Linux, you can specify #! aka “shebang” commands, as shown in the following code:

  #!/usr/bin/dotnet run
  

This allows you to execute the .cs file without prefixing it with the dotnet run command. You must also mark the .cs file as executable in the filesystem. For example, at the command prompt or terminal: ./hello.cs

These #: directives allow for greater flexibility and control directly within your script.

Converting a file-based app to a project-based app

You can later convert it into a full project, as shown in the following command:

dotnet project convert app.cs

Publishing a file-based app

You can publish a file-based app, as shown in the following command:

dotnet publish app.cs

By default, it is published as a native-compiled AOT app. You can disable that by setting a property at the top of the file, as shown in the following code:

#:property PublishAot=false

To learn more about the file-based app feature, you can read the article found at the following link: https://devblogs.microsoft.com/dotnet/announcing-dotnet-run-app/ and for a visual demonstration, you can watch the following video: https://www.youtube.com/watch?v=98MizuB7i-w.