In C# 10 and later, what do global using directives and the SDK's ImplicitUsings setting do, and why can they cause CS0104 errors?
answer
- one directive, every file
- a generated .GlobalUsings.g.cs
- seven namespaces for a console app
- more imports, more name clashes
basics
~20 sA 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).
solid answer
~40 s`global using System.Text.Json;` (C# 10) acts as if that directive opened every file in the project. It can be combined with `static` and with an alias, must precede the file's non-global usings (CS8915), and cannot sit inside a namespace (CS8914). `ImplicitUsings` is an SDK feature built on it: with `<ImplicitUsings>enable</ImplicitUsings>`, which new templates set, the SDK writes `<Project>.GlobalUsings.g.cs` into `obj` with `global using` lines for `System`, `System.Collections.Generic`, `System.IO`, `System.Linq`, `System.Net.Http`, `System.Threading` and `System.Threading.Tasks`. Because every file now imports all of those, a file that adds `using System.Timers;` gets CS0104 for `Timer`, which also exists in `System.Threading`. Fix it with an alias such as `using Timer = System.Timers.Timer;`, which wins over namespace imports, or with the full name.
code
csharp · 4 linesusing System.Timers;
var heartbeat = new Timer(5000);
Console.WriteLine(heartbeat.Interval);go deeper
Recall that a global using imports a namespace into every file and that new projects get common namespaces such as System and System.Linq without writing any using.
Explain where implicit usings come from (the generated .GlobalUsings.g.cs), the CS8915 and CS8914 placement rules, and why more imports make CS0104 more likely.
Diagnose an ambiguity by reading the generated global usings, fix it with an alias or a full name, and spot when a global import of an internal namespace is what caused it.
Set a short global-usings policy: common framework namespaces only, no global imports of internal namespaces with generic type names, one file that reviewers can audit.
## What a global using directive does A normal `using` directive imports a namespace for **one file**. A **global using directive**, added in C# 10, imports it for **every file in the compilation**, which for most code means the whole project. The rules: - It accepts the same forms as a normal directive: `global using System.Text.Json;`, `global using static System.Math;` and `global using Checkpoint = (string Script, int Version);`. - In any file, every `global using` must come before the non-global ones; otherwise the compiler reports **CS8915**, "A global using directive must precede all non-global using directives." - It may not appear inside a namespace declaration, block or file-scoped: **CS8914**, "A global using directive cannot be used in a namespace declaration." - Their order does not matter, inside one file or across files, so teams usually keep them together in one `GlobalUsings.cs`. A `global using static` or a global alias has the same reach: `global using static System.Math;` lets every file call `Max` by its simple name, which is convenient in a calculation-heavy project and surprising for someone reading one file, because nothing in that file says where `Max` comes from. ## What ImplicitUsings adds **Implicit usings** are not a language feature; they are the .NET SDK generating global using directives for you. When the project sets `ImplicitUsings` to `enable` (the console, library and web templates do), the build writes a file named `<ProjectName>.GlobalUsings.g.cs` into the intermediate output folder, for example `obj/Debug/net10.0/Migrator.GlobalUsings.g.cs`, and compiles it with your code. For a project using `Microsoft.NET.Sdk` it contains: 1. `System`, `System.Collections.Generic`, `System.IO` and `System.Linq` 2. `System.Net.Http` (not added when targeting .NET Framework) 3. `System.Threading` and `System.Threading.Tasks` Other SDKs, such as the web SDK, add more. That generated file is the place to look when a name resolves somewhere unexpected; the project file's `<Using>` items can add or remove entries, which is project configuration rather than C#. ## How the compiler treats imported names For a simple name such as `Timer`, C# searches from the innermost namespace outward. At each level it checks the namespace's **own members** first, then that level's **aliases**, then the types imported by its **using directives**; global usings join the file-level directives at the outermost level. Two consequences: - If two imported namespaces each contain an accessible type with that name, and nothing closer matches, the reference is ambiguous: **CS0104**. - A type declared in the namespace you are writing in, or an alias in the file, wins before imports are consulted, so it never collides with them. ## Checking what a file actually imports When a simple name binds to the wrong type, or to two types, check the sources of imports in this order: 1. The `using` directives at the top of the file, and any written inside its namespace declaration. 2. Every `global using` in any file of the project; searching the code for `global using` finds them all. 3. The SDK-generated `.GlobalUsings.g.cs` under `obj`, which reflects the `ImplicitUsings` setting and any `<Using>` items. 4. The types declared in the enclosing namespaces, which are found before any of the imports above. ## Typical collisions and their fixes | Situation | Diagnostic | Fix | |---|---|---| | `using System.Timers;` plus implicit `System.Threading`, then `new Timer(5000)` | CS0104 between `System.Timers.Timer` and `System.Threading.Timer` | `using Timer = System.Timers.Timer;` or the full name | | `global using MigrationTool.Data;` where that namespace declares a `File` class | CS0104 with `System.IO.File` in files outside `MigrationTool.Data` | rename the class, or alias one side | | A class `Task` declared in your own namespace | none inside that namespace: your `Task` wins over `System.Threading.Tasks.Task` | rename it if that code also needs the framework type | Making a directive `global` never resolves an ambiguity: two global imports of `Timer` are still two candidates. ## A layout that stays readable Take a migration tool whose team turns on implicit usings and adds a `GlobalUsings.cs`. A workable policy is to put only namespaces that most files need in that file, keep feature-specific imports in the files that use them, and avoid globally importing your own namespaces whose type names are generic (`File`, `Task`, `Timer`). Then a reader of any file can find every import in two places: the file itself and the global list.
- Where can you see exactly which implicit usings a project gets?In the file the SDK generates in the intermediate output folder, named `<ProjectName>.GlobalUsings.g.cs`, for example `obj/Debug/net10.0/Migrator.GlobalUsings.g.cs`. It holds plain `global using` lines, so it is the first place to check when a simple name binds to an unexpected type.
- Why can a global using for your own namespace break files that compiled before?Every file now imports that namespace's types. If one is named like a type from another imported namespace, such as a `File` class next to `System.IO.File`, files outside that namespace get CS0104. Code inside the declaring namespace still compiles, because a namespace's own members are found before any imports.
- Can a `global using` follow normal `using` lines in the same file?No. Every `global using` in a file must precede the non-global directives, or the compiler reports CS8915. It also cannot appear inside any namespace declaration (CS8914).
- A global using only applies to files in the same folder.
- Implicit usings are a compiler feature that every C# 10 compilation turns on.
- Global using directives can be placed inside a namespace declaration.
- Two imported types with the same name are resolved by import order.
- Making a using directive global fixes a CS0104 ambiguity.