skip to content

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%

answer

  1. a semicolon instead of braces
  2. one per file, nothing nested
  3. only usings may come before it
  4. usings after it sit inside it

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.

solid answer

~40 s

A **file-scoped namespace** (C# 10), `namespace MigrationTool;`, is defined as equivalent to wrapping the rest of the file in `namespace MigrationTool { ... }`, so type names and behaviour are unchanged; only a level of nesting goes away. The compiler enforces three placements: one per file (CS8954), no block-scoped namespace anywhere in the same file (CS8955), and nothing but `extern alias` and `using` directives before it (CS8956). That last rule means a file with top-level statements cannot use one. `using` directives written after the declaration belong to the namespace body: their imports are searched after the namespace's own members, and an alias there may use names the file-level usings import. A `global using` cannot follow it (CS8914).

code

csharp · 11 lines
csharp
using System.Text;

namespace MigrationTool;

using Sb = StringBuilder;          // inside the namespace: the file-level using System.Text applies
using static System.Console;

class Runner
{
    static void Main() => WriteLine(new Sb("running ").Append(typeof(Runner).FullName));
}

go deeper

for a junior

Recall that namespace X; applies to the whole file, saves a level of braces and indentation, and produces the same types as the block form.

for a middle

Explain the three placement errors (CS8954, CS8955, CS8956), why top-level statements cannot share the file, and what happens to using lines written after the declaration.

for a senior

Plan a repository-wide conversion: split multi-namespace files first, keep using placement consistent, and land it as an isolated formatting commit.

for a principal

Standardise one namespace style and one using placement for the codebase and enforce them with the style analyzers, so the choice is made once instead of in every review.

## The syntax and what it means A **block-scoped namespace** wraps its members in braces: `namespace MigrationTool { class Runner { } }`. A **file-scoped namespace declaration**, added in C# 10, ends with a semicolon instead: `namespace MigrationTool;`. The language defines it as equivalent to a block namespace whose body is the rest of the file. So `Runner` is still `MigrationTool.Runner`, the compiled types and their metadata names are identical, and converting a file changes no behaviour. What it removes is one level of indentation in every file, which is why the C# documentation recommends it for new code. These two files declare the same type: ```csharp // Block-scoped namespace MigrationTool { public sealed class Runner { } } // File-scoped (C# 10) namespace MigrationTool; public sealed class Runner { } ``` Because the result is the same namespace, the styles mix freely across files: a `partial` class can have one part in a block-scoped file and another in a file-scoped one, and `typeof(Runner).Namespace` is `MigrationTool` either way. ## What the compiler rejects | File layout | Result | |---|---| | `namespace A;` then classes | compiles | | `namespace A;` then `namespace B;` | error **CS8954**, "Source file can only contain one file-scoped namespace declaration." | | `namespace A;` then `namespace B { }`, or a block namespace containing `namespace B;` | error **CS8955**, "Source file can not contain both file-scoped and normal namespace declarations." | | a class, or a top-level statement, before `namespace A;` | error **CS8956**, "File-scoped namespace must precede all other members in a file." | | `namespace A;` then `global using ...;` | error **CS8914**, a global using cannot be used in a namespace declaration | Two practical consequences: - A file that needs types in **two namespaces** must use block namespaces for both, or, better, be split into two files. - **Top-level statements and a file-scoped namespace cannot share a file.** Statements must come before any namespace declaration, and the file-scoped declaration must come before every member, so the combination is CS8956. Top-level statements always live in the global namespace; namespaced types go in other files. ## Using directives before and after the declaration Normal `using` directives may appear above `namespace MigrationTool;`, below it, or both, but always before the first type; a `using` between two classes is error **CS1529**. The position matters: 1. Directives **above** the declaration belong to the compilation unit, the outermost scope. 2. Directives **below** it belong to the namespace body, exactly as if they were written just inside the braces of a block namespace. 3. A simple name is looked up from the inside out: the namespace's own members, then the body's aliases and imports, then the enclosing (global) namespace's members, then the file-level aliases and imports. 4. An alias below the declaration may use names imported above it, because those belong to an outer scope; an alias is resolved without the directives of its own level. So `using Sb = StringBuilder;` fails with CS0246 at the top of a file that also says `using System.Text;`, yet compiles when written below `namespace MigrationTool;`. ## Converting an existing codebase For a tool such as a database migrator, the conversion is mechanical and safe: - Replace `namespace X {` with `namespace X;`, delete the closing brace, and remove one indentation level; IDE refactorings can apply this across a project. - Split any file that declares more than one namespace first, since those cannot convert. - Leave `Program.cs` alone if it uses top-level statements: it has no namespace to convert. - Do not add a namespace to a file whose types were deliberately in the global namespace without checking callers: their full names change, and code that reached them without a `using` stops compiling. - Keep the existing choice of `using` placement (above or below the namespace line) consistent, because moving directives inside changes the lookup order described above. Because the conversion touches every line of every file, land it as a separate whitespace-only commit so reviewers and blame history are not buried in it.

  • Can a `Program.cs` that uses top-level statements also declare `namespace MigrationTool;`?
    No. Top-level statements must precede namespace declarations, and a file-scoped namespace must precede every other member, so the compiler reports CS8956. Top-level statements always run in the global namespace; declare namespaced types in other files.
  • What changes when a file's `using` lines move from above `namespace MigrationTool;` to below it?
    They become directives of the namespace body. Their imports are searched after the namespace's own members but before anything at file level, and an alias written there may use names the file-level usings import. Usually nothing visible changes, but an ambiguity or a shadowed name can resolve differently.

  • A file-scoped namespace changes the compiled type names or IL.
  • A file may declare two file-scoped namespaces one after another.
  • A block namespace may be nested inside a file-scoped namespace.
  • Using directives are not allowed after a file-scoped namespace line.
  • Top-level statements can come before a file-scoped namespace in Program.cs.