Top-level statements and Main

Top-level statements

A file with statements and no class is a program. The compiler takes the statements as the body of the entry point, in the order they are written, and the local variables of the file are local variables of that method. That is what every program of the last two lessons did.

using System.Reflection; Console.WriteLine($"args: {args.Length}"); Console.WriteLine($"entry point: {Assembly.GetEntryAssembly()?.EntryPoint}");

dotnet run

args: 0
entry point: Void <Main>$(System.String[])

The name of the entry point is the interesting part: <Main>$ is not a name a person wrote, it is the name the compiler gave the method it generated. The $ is not legal in a C# identifier, so the generated method can never collide with one of yours.

What the compiler generates

A top-level program is a class named Program with a static void Main(string[] args), and the statements are its body. Two consequences follow, and both surprise a beginner:

The entry point is a method like any other, so a program that grows past a screen is easier to read with an explicit class and Main. The course uses top-level statements for the short examples and comes back to classes in the part on classes.

Main and its four signatures

An explicit entry point may be written in four ways, and each one is Main with a static in front:

The int form returns the exit status, and args is the command line without the program name. Methods with these signatures may be private or public, and the compiler takes the one it finds; two overloads of Main in one class are an error.

class Program { static int Main(string[] args) { Console.WriteLine($"classic main, args: {args.Length}"); return args.Length == 0 ? 2 : 0; } }

dotnet run
echo "status: $?"

classic main, args: 0
status: 2

Returning an exit status

The number Main returns is the exit status of the process, and the shell reads it as $?. Zero means success by convention, and any other number is a failure the caller can test. The program above returns 2 when it gets no argument, which is how a command-line tool says "you used me wrongly" without a message on stderr.

A top-level program has no return value: its generated Main returns void. To leave a status from it, call Environment.Exit(code), or set Environment.ExitCode and let the program end normally. The lesson on arguments and exit codes uses both.

async Task Main

A fifth form is allowed and is not in the list above because its return type is not int: an entry point may be static async Task Main() or static async Task<int> Main(string[] args). The runtime starts the method, waits for the task it returns, and uses its result as the exit status.

class Program { static async Task Main() { Console.WriteLine("before await"); await Task.Delay(10); Console.WriteLine("after await"); } }

dotnet run

before await
after await

Top-level statements may use await as well, and the compiler makes the generated Main asynchronous when they do. The part on async and await reads what the compiler builds for a method like this one.

Exercises

  1. Add a second file with a top-level statement to a project that already has one. Read CS8802 and say which of the two files the compiler kept.
  2. Change the classic Main to return args.Length and run it with three arguments. Which status does the shell see?
  3. Give the classic program both static void Main() and static int Main(string[] args). Read the error.
  4. Write a top-level program that ends with Environment.ExitCode = 7; and no Exit call. Which status does it leave, and why does the program still run to its end?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which name does the compiler give the entry point of a top-level program?

    Answer

    <Main>$ in a generated class named Program

    The compiler writes a class Program with a method <Main>$, a name no C# source can write, and the statements become its body.

  2. How many files of one project may hold top-level statements?

    Answer

    One

    A second file with top-level statements fails with CS8802, because the project would have two entry points.

  3. What does this program print, and with which exit status? class Program { static int Main(string[] args) { Console.WriteLine($"args: {args.Length}"); return 2; } }

    Answer

    args: 0 / exit status: 2

    No arguments were passed, so args is empty, and the value Main returns becomes the exit status of the process.

  4. What does this program print? class Program { static async Task Main() { Console.WriteLine("one"); await Task.Delay(1); Console.WriteLine("two"); } }

    Answer

    one / two

    An async Task Main is a legal entry point; the runtime waits for the task, so both lines print.

  5. Which signatures may an explicit entry point have?

    Answer

    static void Main(), static void Main(string[]), static int Main(), static int Main(string[])

    The four void and int forms are the classic set, and the async Task forms are allowed on top of them.

  6. What does this program print? Console.WriteLine("start"); Environment.ExitCode = 5; Console.WriteLine("end");

    Answer

    start / end, then exit status 5

    ExitCode only sets the status the process will leave; the program keeps running to its last statement.

  7. What does this program print, and with which exit status? class Program { static int Main() => 4; }

    Answer

    exit status: 4

    An expression-bodied Main returns 4 without printing anything, and the returned value is the exit status.

  8. What happens when a class declares both static void Main() and static int Main(string[] args)?

    Answer

    error CS0017: Program has more than one entry point defined.

    Two candidate entry points in one program are ambiguous, and the compiler reports CS0017 and stops.

  9. What does this program print? Console.WriteLine(typeof(Program).FullName);

    Answer

    Program

    A top-level program generates a class named Program in the global namespace, and its full name is just Program.

  10. Which statement about the variables of a top-level file is true?

    Answer

    They are locals of the generated Main and usable by the statements that follow

    The statements become one method body, so a var declared on one line is a local of that method for the lines after it.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev