Skip to content
Tutorials Center
My learning

Topics

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.

C#
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.

C# A program without Main

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.

C# Statements after a type (compile error)

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.

C#
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 static to 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, and Environment.Exit works as usual. The generated class is internal, 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.cs as a few lines that build and start the app, and put logic in classes.
  • Explicit Main is still fine. A classic static void Main(string[] args) works in the same projects. If a project has both top-level statements and an explicit Main, 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 0 means 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.cs does the same on your machine (The dotnet CLI).