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:
- A file may hold top-level statements or a class called Program with a Main, and only one file of a project may hold top-level statements. A second one is error CS8802: Only one compilation unit can have top-level statements.
- Type declarations may follow the statements in the same file: they are members of the generated class or of the namespace the file sits in. The first lesson used that for its Temperature class.
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:
- static void Main()
- static void Main(string[] args)
- static int Main()
- static int Main(string[] args)
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
- 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.
- Change the classic Main to return args.Length and run it with three arguments. Which status does the shell see?
- Give the classic program both static void Main() and static int Main(string[] args). Read the error.
- 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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
What happens when a class declares both
static void Main()andstatic 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.
-
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.
-
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