C# 9.0: Top-level Statements. Or Should I Say: Hey, Where’s the Main Method?

Thomas Claudius Huber · August 18, 2020

C# 9.0: Top-level Statements. Or Should I Say: Hey, Where’s the Main Method?

By Thomas Claudius Huber .NET, C# 46 Comments

C# 9.0 introduces many new language features, and with this blog post I start a little series to look at some of those new features. Let’s start in this post with top-level statements.

When you create a new Console application with C#, you get a lot of boilerplate code. Below you see the code of a new app with the name ThomasClaudiusHuber.ConsoleApp.

using System;

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

If you’re new to C#, this program will confront you with a lot of concepts:

using directives
namespaces
blocks { }
classes
static methods
void return type
array parameters
Console.WriteLine statement

Already in earlier versions of C# and .NET the namespace was optional. Also the args parameter of the Main method is optional. You could write the program like this without the namespace block and the args parameter:

using System;

class Program
{
    static void Main()
    {
        Console.WriteLine("Hello World!");
    }
}

This means, from our list, you can remove namespaces and array parameters:

using directives
namespaces
blocks { }
classes
static methods
void return type
array parameters
Console.WriteLine statement

C# 9.0, which comes out with .NET 5, brings all of this to the next level by allowing so-called top-level programs. That means you can write statements directly at the top-level of a file. There’s no need to define a class and a static Main method. The code below shows a Hello World Console app written with C# 9.0:

using System;

Console.WriteLine("Hello World!");

Now, when you look at the list of features that we have here compared to the original Console app, it looks like below. Only the using directive and the Console.WriteLine statement are left:

using directives
namespaces
blocks { }
classes
static methods
void return type
array parameters
Console.WriteLine statement

This makes it clear that simple top-level programs are an easy way to start with C#. Beginners don’t have to learn all the different features from the beginning.

When you use .NET 5 for your project, it defaults to C# 9.0 as a language version. So, just ensure your project runs on .NET 5 by looking at the .csproj file and ensuring that the TargetFramework is set to net5.0:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>

</Project>

To target .NET 5, you need the .NET 5 SDK. You can download and install the .NET 5 SDK from here.

Where’s the Main Method?

Good question. If you worked with .NET in the past, you learned that the entry of every .NET program is the static Main method. But in a top-level program, that Main method does not exist, as we have just this code:

using System;

Console.WriteLine("Hello World!");

So, where the heck is our Main method? Let’s look what code gets generated by using the classic tool available, the Intermediate Language Disassembler, or short ILDASM (There are more powerful alternatives like ILSpy or dnSpy, but ILDASM does the job here).

If you’ve installed Visual Studio 2019, you find a Visual Studio 2019 folder in your start menu. In that folder is the Developer Command Prompt for Visual Studio 2019.

In the Developer Command Prompt, just write ildasm and press Enter to open the Intermediate Language Disassembler, as you can see in the screenshot below. Note that this works only in the Developer Command Prompt and not in a normal command prompt, as the Developer Command Prompt has the Path set accordingly, so that the ILDASM.exe is found.

In the Intermediate Language Disassembler, let’s open the .dll file of our Console app which uses C# 9’s top-level program feature. In the screenshot below I’ve opened the .dll file. You can see that a $Program class and a static $Main method was generated behind the scenes for us. This means there is still a static Main Method, but it’s auto-generated if you create a top-level program where you don’t define that Main method explicitly in your code.

When you double-click that $Main method, you can see the Intermediate Language Code. You can see it in the screenshot below. The code shows you that the top-level Console.WriteLine statement is actually added to that generated $Main method. This means in other words: All your top-level statements are added to the generated $Main method.

Commandline Arguments

When you look at the auto-generated $Main method in the screenshot above, you can see that the $Main method has also the conventional string[] parameter for command line arguments. As the top-level statements that you write in a top-level program file are put into that auto-generated $Main method, you can also access that string[] parameter, that has conventionally the name args. So you can write something like this in a top-level program to print out the command line arguments to the console:

using System;

if (args?.Length > 0)
{
    foreach(var arg in args)
    {
        Console.WriteLine(arg);
    }
}

There Can be Only ONE Main-Method File with Top-level Statements

Yes, there can be only one Main method in .NET programs. If you define multiple Main methods, you get a compile error unless you compile with the /main flag to define the entry point.

For a file with top-level statements, a $Main method is generated and set as entry point. As there can be only one entry point for your .NET app, there can be only exactly one file in your project that has top-level statements. Let’s test this: In my Console app I added a Customer.cs file, in addition to the existing Program.cs file, and I tried to use a top-level statement there as well. In the screenshot below you can see that I get the error “Only one compilation unit can have top-level statements”, which means that you can use top-level statements only in a single file of your project.

Using Types and Namespaces

When you declare namespaces and/or types in your top-level program file, these declarations must be after all top-level statements, else you’ll get a compile error. For example, look at the file below. It declares the Friend type before the top-level statements, which leads to an error on the first statement:

The correct order for that program is like shown in the code below. As you can see, the class Friend is declared after the two top-level statements to create a Friend and to print out the friend’s firstname to the console:

using System;

var friend = new Friend { FirstName = "Thomas" };

Console.WriteLine($"Hello {friend.FirstName}!");

class Friend
{
    public string FirstName { get; set; }
}

When you look at the generated Intermediate Language code in ILDASM for the program of the code snippet above, you can see that the type Friend is created as it would be in a separate file (You can also wrap the Friend class in a namespace block if you want). This means the C# compiler takes the top-level statements that you have to define first, moves them to the generated $Main method and then it compiles all the types in that top-level file as it would compile them in any other C# file.

Summary

I think top-level programs are a great addition to C#. It makes it quite easy to play with the language. And especially for simple projects it is great that you don’t have the additional namespace, class and Main method in your code. .NET auto-generates all that boilerplate stuff for you behind the scenes, which is great. I like this feature.

I think the downside is that beginners might not really understand what happens behind the scenes. But is that necessary to start with C#? Maybe not if you have only a single file in your project. But if I explain C# to a new developer, I start with the Main method, saying that this is the entry point of the program. This is something everyone understands. Your program starts exactly here! With a top-level file I have to say that the file with top-level statements is the entry point of the program. And now, what is simpler for a beginner:
a) finding the file with the top-level statements
b) finding the Main method

Hm, if there’s only one file, it’s easy and it doesn’t matter too much, but with multiple files and without knowing the concepts of namespaces, classes and methods it’s hard to know what a top-level statement actually is. So I think it’s definitely b), finding the Main method is easier than finding a file with top-level statements.

So, I think top-level statements are great to play with the language in a single file, and they are great for simple applications where you don’t have too many files. But if you consider becoming a .NET developer, I recommend you to start where everything begins: In the Main method. :)

I hope this blog post helps you to understand the new top-level statement feature of C# 9.0 a bit better. In the next blog post you learn about init-only properties.

Happy coding,
Thomas