skip to content

Entry Points & Namespaces

A C# program starts in top-level statements or a Main method, organised by file-scoped namespaces and global or aliased usings. Interviewers ask what the compiler generates.

on this pageshow

explore

questions

6

In C#, what does the compiler generate for a Program.cs written with top-level statements, and how do args, await and return shape it?

level: juniorimportance: must knowfreq 68%

answer

  1. a class you never wrote
  2. partial Program, global namespace
  3. args is a parameter, never null
  4. the body picks the return type

basics

~20 s

The compiler wraps the statements in a generated static entry-point method of a partial class Program in the global namespace. args is its string[] parameter; await makes it return Task, a returned value makes it int, and both give Task<int>.

solid answer

~40 s

Top-level statements are shorthand for an entry point. The compiler moves them into a static method of a generated `partial class Program` in the global namespace; the method has a name C# cannot spell (`<Main>$`), so nothing can call it, and its one parameter, `string[] args`, is never null. The body picks the signature: no `await` and no returned value gives `void`, `return 2;` gives `int`, `await` gives `Task`, and both give `Task<int>`, whose result becomes the process exit code. Locals and local functions declared there are locals of that method, so a type member cannot use them (CS8801). Only one file in a project may hold top-level statements (CS8802), they must come before any namespace or type declaration (CS8803), and an old `static Main` left in the project is ignored with warning CS7022.

code

csharp · 16 lines
csharp
using System.Reflection;

if (args.Length == 0)
{
    Console.WriteLine("usage: migrate <target-version>");
    return 2;
}

await Task.Delay(50); // stands in for applying migration scripts

const BindingFlags Statics = BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.DeclaredOnly;
foreach (MethodInfo m in typeof(Program).GetMethods(Statics))
    Console.WriteLine($"{m.ReturnType.Name} {m.Name}(string[] {m.GetParameters()[0].Name})");
Console.WriteLine($"entry point: {Assembly.GetEntryAssembly()!.EntryPoint!.Name}");
Console.WriteLine($"migrated to {args[0]}");
return 0;

go deeper

for a junior

Recall that the statements become the body of a generated entry point in a Program class, that args is available, and that return 0 or return 2 sets the exit code.

for a middle

Explain how await and a returned value select among four signatures, why top-level locals are invisible to types (CS8801), and the one-file and statements-first rules.

for a senior

Show a safe conversion of a legacy entry point: keep the exit-code contract scripts depend on, delete the old Main rather than hiding it behind CS7022, and use partial Program for shared static members.

for a principal

Treat it as a style decision, not a performance one: both forms compile to equivalent code, so standardise new entry points and leave stable ones alone unless they are being edited anyway.

## What a top-level file compiles to **Top-level statements** (C# 9) let a program start with ordinary statements instead of a `class Program` with a `static void Main`. Nothing is interpreted: the compiler still emits a normal entry point. It creates a class named `Program` in the **global namespace** (no namespace at all), marks it `partial`, and puts the statements into a **static method** whose metadata name is `<Main>$`. Because angle brackets are not legal in a C# identifier, no source code can call that method by name. The method always has one parameter, `string[] args`, which holds the command-line arguments and is never `null`; with no arguments its `Length` is 0. ```csharp // What you write in Program.cs if (args.Length == 0) return 2; await ApplyMigrationsAsync(args[0]); return 0; // Roughly what the compiler produces (the method name is not legal C#) partial class Program { static async Task<int> <Main>$(string[] args) { /* the statements */ } } ``` ## The four generated signatures The **body** decides the return type. Only a `return` that carries a value counts; a bare `return;` does not. | Top-level code contains | Generated signature | |---|---| | neither `await` nor `return value;` | `static void <Main>$(string[] args)` | | `return value;` only | `static int <Main>$(string[] args)` | | `await` only | `static Task <Main>$(string[] args)` | | `await` and `return value;` | `static Task<int> <Main>$(string[] args)` | When the method returns a task, the compiler adds a second, synchronous method named `<Main>`. That bridge is the real entry point recorded in the assembly: the runtime calls it, it calls `<Main>$`, waits for the task, and returns the `int` (if any) as the **process exit code**. An exception thrown after an `await` therefore surfaces through the bridge as an unhandled exception, and a stack trace shows both frames: `Program.<Main>$` above `Program.<Main>`. ## Rules that follow from the generated method - **One file only.** Every program has one entry point, so only one file in a project may contain top-level statements; a second one is error **CS8802** ("Only one compilation unit can have top-level statements."). - **Statements first.** `using` directives come first, then the statements, then any namespaces or types; a statement after a type is error **CS8803**. - **Locals stay local.** A variable or local function declared at the top level is a local of the generated method. A class that reads it is error **CS8801**, even in the same file. Share state through a static member instead. - **`Program` is partial.** You may add members with your own `partial class Program { ... }`; declaring `class Program` without `partial` is error **CS0260**. - **Every path returns.** Once one `return` carries a value, all paths must: falling off the end is error **CS0161**, reported against `<top-level-statements-entry-point>`. - **An explicit `Main` is ignored.** A `static Main` left beside top-level statements compiles but is not used; the compiler warns **CS7022** ("The entry point of the program is global code; ignoring ... entry point."). ## What stays the same Top-level statements change the source, not the program: - The output is an ordinary executable with an ordinary entry point; there is no script host and no extra start-up step. - `Program` is a real type, so `typeof(Program)` works and other code in the project can call static members you add to `partial class Program`. - Local functions declared among the statements behave like local functions anywhere: they can capture top-level locals and can be called before the line that declares them. - File-level `using` directives, global usings from other files and implicit usings apply to the top-level file exactly as to any other file. ## Converting a classic Program class Take a database-migration command-line tool that still has `static async Task<int> Main(string[] args)` inside `class Program`. Converting it is mechanical: 1. Move the body of `Main` to the top of `Program.cs`, after the `using` directives, and delete the class and method wrapper. 2. Keep every `return` code the deployment scripts check; the generated `Task<int>` method returns them exactly as before. 3. Move helper methods that were static members of `Program` either into local functions at the end of the statements, into `partial class Program` after them, or into their own class. 4. Delete the old `Main` instead of leaving it behind a CS7022 warning, and make sure no other file in the project has statements at the top level. Both styles compile to equivalent code, so there is no run-time reason to convert a stable entry point; the gain is less ceremony in the file a new reader opens first.

  • Why does adding `return 2;` inside an early-exit `if` break a top-level file that ends without a return?
    Once any `return` carries a value, the generated method returns `int` (or `Task<int>` with `await`), so every path must return one. The compiler reports CS0161, 'not all code paths return a value', against the top-level entry point. Add `return 0;` at the end; a bare `return;` would not change the signature.
  • Can a helper class in the same project read a variable declared in the top-level statements?
    No. That variable is a local of the generated method, and using it from a type member is error CS8801 ('Cannot use local variable or local function ... declared in a top-level statement in this context'). Put shared state in a static member, for example in `partial class Program` or a dedicated static class.
  • What happens to the old `static Main` if it stays in the project after the conversion?
    It still compiles, but it is no longer the entry point: the compiler warns CS7022 that the entry point is global code and ignores that `Main`. The program runs the top-level statements. Delete the old method so nobody keeps editing dead code.

Top-level statements are like writing only the body of a letter while the stationery adds the envelope: the envelope is still there, addressed and stamped, you just never handled it.

  • Top-level statements run as a script without compiling any Main method.
  • Top-level code has no args, so you must call Environment.GetCommandLineArgs.
  • Each file in a project can have its own top-level statements.
  • Variables declared at the top level become fields any class can read.
  • A program written with top-level statements cannot set an exit code.
open as a page

In C# 10 and later, what does a file-scoped namespace declaration change, and which placements in a file does the compiler reject?

level: middleimportance: should knowfreq 40%

basics

~20 s

namespace MigrationTool; places every type in the file in that namespace without braces, like a block namespace around the rest of the file. A file gets one, cannot mix it with block namespaces, and must declare it before any type or statement.

open as a page

In C# 10 and later, what do global using directives and the SDK's ImplicitUsings setting do, and why can they cause CS0104 errors?

level: middleimportance: should knowfreq 45%

basics

~20 s

A global using applies one using directive to every file in the compilation, and ImplicitUsings makes the .NET SDK generate such directives for common namespaces like System. More imports mean more simple names, so same-named types turn ambiguous (CS0104).

open as a page

Which static Main signatures does the C# compiler accept as a program's entry point, and what changes when Main is async Task<int>?

level: middleimportance: should knowfreq 50%

basics

~20 s

A C# entry point is a static Main returning void, int, Task or Task<int>, taking nothing or one string[]. async is legal only on the task forms, and the compiler then adds a bridge that waits and returns the int as the exit code.

open as a page

A C# class Migration sits in namespace MigrationTool.Migration; why does new Migration() compile in the top-level Program.cs but fail with CS0118 inside namespace MigrationTool?

level: seniorimportance: should knowfreq 30%

basics

~20 s

C# resolves a simple name from the innermost namespace outward, checking each namespace's own members before its using directives. Inside MigrationTool, Migration first matches the namespace MigrationTool.Migration, giving CS0118; the global namespace has no such member, so Program.cs reaches the using.

open as a page

In C#, what do using static and using alias directives bring into scope, and which types can a C# 12 using alias name?

level: middleimportance: nice to knowfreq 28%

basics

~20 s

using static imports one type's static members and nested types; a using alias gives a namespace or type a second name. Since C# 12 an alias can name any type, such as a tuple or array, but never a nullable reference type.

open as a page