skip to content

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%

answer

  1. lookup walks outward
  2. members before imports
  3. a namespace is a member too
  4. rename, qualify or alias differently

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.

solid answer

~40 s

Simple-name lookup goes scope by scope from the inside out, and at each namespace level the namespace's **members**, which include nested namespaces, are checked before that level's aliases and `using` imports. Code inside `namespace MigrationTool` finds the member namespace `MigrationTool.Migration` under the name `Migration` and stops there, so `new Migration()` is CS0118, "'Migration' is a namespace but is used like a type". The top-level statements live in the global namespace, which has no member named `Migration`, so lookup reaches the file's `using MigrationTool.Migration;` and finds the class. Moving the using inside the namespace does not help, and a same-named alias there is CS0576. Fix it by renaming the namespace (for example `Migrations`), qualifying the type as `Migration.Migration`, or aliasing it under a different name.

code

csharp · 20 lines
csharp
using MigrationTool.Migration;

Console.WriteLine(new Migration().Id);          // global namespace: compiles
Console.WriteLine(MigrationTool.Runner.Apply());

namespace MigrationTool.Migration
{
    public class Migration
    {
        public string Id { get; init; } = "0001_init";
    }
}

namespace MigrationTool
{
    public static class Runner
    {
        public static string Apply() => new Migration().Id;   // CS0118
    }
}

go deeper

for a junior

Recall that a namespace and a class can share a name and that the compiler then may treat Migration as the namespace, reported as CS0118.

for a middle

Explain the lookup order: enclosing namespaces from the inside out, each one's members before its using directives, and why the global namespace behaves differently.

for a senior

Diagnose CS0118 and CS0576 quickly, reject the fixes that only move or alias the using, and choose between renaming and qualifying based on how far the name has spread.

for a principal

Make plural namespace names and no namespace-type name clashes part of the team's naming standard, so the trap is removed rather than patched file by file.

## Reproducing the problem A database-migration tool keeps its migration types in a folder named `Migration`, and the IDE derived the namespace from it: `MigrationTool.Migration`. The main class in that namespace is also called `Migration`. The top-level `Program.cs` says `using MigrationTool.Migration;` and `new Migration()` compiles. A `Runner` class in `namespace MigrationTool` has the same using line and the same expression, and the build fails with **CS0118**: "'Migration' is a namespace but is used like a type". Nothing is wrong with the class; the name never reaches it. ## How C# resolves a simple name For a name like `Migration` with no type arguments, the compiler walks outward from the code's location: 1. Locals, parameters, type parameters and members of the enclosing types, innermost first. 2. For each enclosing namespace declaration, innermost first: the namespace's **own members** (its types and its **nested namespaces**), then the aliases and the types imported by the `using` directives written in that declaration. 3. Finally the global namespace: its members, then the compilation unit's aliases, imports and the global usings. The first level that produces a match wins. In `Runner`, level 2 for `MigrationTool` finds the **namespace** `MigrationTool.Migration` under the simple name `Migration`. A namespace cannot be constructed, so the compiler reports CS0118 instead of continuing to the using directive. In `Program.cs`, the code is already in the global namespace, which contains `MigrationTool` but nothing called `Migration`, so the file's using directive supplies the class. ## Diagnosing it quickly 1. Read the number: CS0118 says the name resolved to the wrong **kind** of entity, not that it is missing (that would be CS0246). 2. Go to the definition of the failing name in the IDE: it lands on the namespace, not the class. 3. Search the namespaces enclosing the failing file for a nested namespace or type with the same simple name. 4. Compare with a file in another namespace, or the top-level file, where the same line compiles; the difference is the enclosing namespace. ## Fixes that look right but fail - **Moving the using inside the namespace.** `namespace MigrationTool;` followed by `using MigrationTool.Migration;` still fails with CS0118: the namespace's own members are checked before the directives in its body. - **A same-named alias inside the namespace.** `using Migration = MigrationTool.Migration.Migration;` below the namespace line gives **CS0576**, "Namespace 'MigrationTool' contains a definition conflicting with alias 'Migration'". - **The same alias at the top of the file.** It belongs to the outermost scope, so the inner namespace member still wins and CS0118 remains. ## Fixes that work | Fix | Example | Trade-off | |---|---|---| | Rename the namespace | `MigrationTool.Migrations` with class `Migration` | touches every using line once; removes the trap for good | | Qualify through the namespace | `new Migration.Migration()` | compiles, but reads like a typo | | Fully qualify from the root | `new global::MigrationTool.Migration.Migration()` | unambiguous and noisy | | Alias under another name | `using MigrationStep = MigrationTool.Migration.Migration;` | local relief; the collision stays for the next file | ## The same trap one level up The collision also works in reverse. If `MigrationTool.Core` declares a class named `MigrationTool`, code inside `MigrationTool.Core` that writes `MigrationTool.Runner.Apply()` now starts from the **class**, because it is a member of the nearer namespace, and fails with **CS0117**, "'MigrationTool' does not contain a definition for 'Runner'". The fix is the same family: rename the class, or write `global::MigrationTool.Runner.Apply()`, where the `global::` qualifier starts lookup at the root namespace. ## Preventing it The .NET Framework design guidelines say: do not use the same name for a namespace and a type in that namespace, and consider plural namespace names where appropriate, as in `System.Collections`. In practice: - Name folders, and therefore namespaces, in the plural (`Migrations`, `Models`, `Handlers`) when they hold a family of types. - Treat CS0118 or CS0576 in review as a naming defect, not something to silence with `global::` everywhere. - Remember the asymmetry when testing: top-level statements in the global namespace can hide the bug that every namespaced file hits. The diagnosis has one right answer once the lookup order is known, which is why it is a favourite senior screening question: it separates knowing that `using` directives exist from knowing when they are consulted.

  • Why doesn't moving `using MigrationTool.Migration;` below `namespace MigrationTool;` fix the error?
    Directives in a namespace body are consulted only after that namespace's own members. `MigrationTool` still has a member namespace named `Migration`, so lookup stops there and the compiler reports CS0118 again.
  • Why does `using Migration = MigrationTool.Migration.Migration;` inside the namespace fail with a different error?
    An alias in a namespace body may not share a name with a member of that namespace. Because `MigrationTool` already contains the namespace `Migration`, the compiler reports CS0576, 'Namespace 'MigrationTool' contains a definition conflicting with alias 'Migration''. Choose another alias name, such as `MigrationStep`.
  • Which naming rule prevents this class of error?
    The .NET design guidelines: do not give a namespace and a type in that namespace the same name, and consider plural namespace names such as `Migrations`. A plural folder and namespace with singular type names keeps the two from colliding.

  • Using directives are consulted before the enclosing namespace's own members.
  • Moving the using inside the namespace gives it priority over namespace members.
  • A same-named alias inside the namespace always beats the nested namespace.
  • CS0118 means the Migration class itself failed to compile.
  • The top-level file compiling proves the namespaced files will compile too.