C# Reference ยท .NET, Tools and Concepts
Top-level statements
Reference for C# top-level statements: write a program without a Main method, use args, await, return an exit code, local functions, and the ordering rules.
Top-level statements let you write the body of your program directly in a file, without a class and a Main method around it. The compiler wraps your statements in a generated entry point for you. It was added in C# 9, and it is the default shape of the console template since .NET 6.
Console.WriteLine("Hello, World!");
Only one file in a project may contain top-level statements. That file's statements run first to last, exactly like the body of Main, and type declarations (classes, records, structs, enums, interfaces, delegates) follow them in the same file or live in other files.
Try it
The statements can use await, local functions and the args array. The program below declares a type at the bottom and uses it above.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
The statements must come before the type declarations. Put a class first, and the compiler rejects the statements that follow it.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
The compiler reports error CS8803: Top-level statements must precede namespace and type declarations. Move the class below the Console.WriteLine line and the program works.
Syntax
There is no special keyword. A file becomes a "top-level" file when it has executable statements outside any type.
using System.Text; // 1. usings var sb = new StringBuilder(); // 2. statements sb.Append("hi"); Console.WriteLine(sb); return 0; // optional exit code record Point(int X, int Y); // 3. type declarations
What the compiler generates
| Feature | Behavior |
|---|---|
| Entry point | A method named <Main>$ in an internal, partial class named Program. Its return type is void, int, Task or Task<int> depending on what you write. |
args |
A string[] with the command-line arguments, in scope for all top-level statements. It is not available inside the other types you declare. |
await |
If the statements use await anywhere, the generated method becomes async. |
return |
return 3; at the top level makes the program return that exit code. |
| Local functions and variables | Declared in the statements, they are locals of the generated method, not members of Program. |
Named Program |
You can write public partial class Program { } to give tests (for example WebApplicationFactory<Program>) a public type to refer to. |
Errors and limits: top-level statements are an error in a second file of the same project (CS8802). Statements after a type or namespace declaration give CS8803. A file-scoped namespace (namespace Demo;) after top-level statements gives CS8956, because it must precede all other members in the file.
Usage notes
- Variables declared at the top are locals, not fields. A method you declare as a class member cannot see them. Local functions written among the statements can, which is why they are the usual helpers. If a class needs a value, pass it in.
- Methods declared among the statements are local functions. They can be
staticto forbid capturing, and they may be written after the statements that call them. - Same behavior as
Main. Exceptions that escape end the process with an error, the exit code rules are the same, andEnvironment.Exitworks as usual. The generated class isinternal, so it never shows up in a library's public API. - Good for small programs. Scripts, demos, tools and ASP.NET Core minimal APIs use it to stay short. For a large program, keep
Program.csas a few lines that build and start the app, and put logic in classes. - Explicit
Mainis still fine. A classicstatic void Main(string[] args)works in the same projects. If a project has both top-level statements and an explicitMain, the compiler warns and uses the statements as the entry point. - No namespace for statements. Put the types you declare in the file in a namespace only if you use a block-scoped one after the statements; most programs simply leave them in the global namespace.
- Exit codes. By convention
0means success. A program that returns a number from the end of its statements can be used from scripts and CI jobs. - Single-file programs. The editors on this site compile your whole input as one top-level file.
dotnet run file.csdoes the same on your machine (The dotnet CLI).