Namespaces, using and ImplicitUsings
A namespace
A namespace is a prefix for type names. System.Text.StringBuilder is the type StringBuilder in the namespace System.Text, and the full name is what the compiler resolves. A file may put its own types into a namespace:
using System.Text;
namespace Shop;
class Program
{
static void Main()
{
var builder = new StringBuilder();
builder.Append("order").Append(' ').Append(42);
Console.WriteLine(builder.ToString().ToUpperInvariant());
}
}
dotnet run
ORDER 42
namespace Shop; is a file-scoped namespace:
it covers the whole file, and no braces are needed. The older form wraps the
declarations in namespace Shop { ... } and may be
repeated in one file. Both are legal in C# 14; the file-scoped form is what
a new file should use, and the braced form is what a file from 2015 has.
A type in a namespace is named by its full name from outside:
Shop.Program. The lesson on
a library and the project that uses it
shows a namespace that spans two projects.
using and aliases
The using directive at the top of a file lets the file write a short type name. Three forms are worth knowing:
- using System.Text; imports the namespace, so StringBuilder is enough.
- using System.Text.StringBuilder; imports one type, which is also legal in C# 10 and later.
- using Text = System.Text; is an alias: the file then writes Text.StringBuilder. An alias is the way out of a clash between two namespaces that hold the same name.
A using is a compile-time name, not a reference to an assembly: the assembly is chosen by the project file, and the directive only saves typing. The compiler error for a missing one is error CS0246: The type or namespace name could not be found, which the lesson on the first compiler error reads line by line.
ImplicitUsings
A new console project sets <ImplicitUsings>enable</ImplicitUsings>, and then a file needs no using for the common namespaces at all. This whole program is four statements and no directive:
var names = new List<string> { "Ada", "Grace", "Linus" };
Console.WriteLine(string.Join(", ", names));
Console.WriteLine(Path.Combine("logs", "app.txt"));
Console.WriteLine(DateTime.UtcNow.Year >= 2026);
dotnet run
Ada, Grace, Linus
logs/app.txt
True
Three namespaces are in play and none is written: System.Collections.Generic for List<T>, System.IO for Path and System for Console, string and DateTime. The build writes the reason into obj as a generated file, and that file is the honest list of what the setting adds:
// <auto-generated/>
global using System;
global using System.Collections.Generic;
global using System.IO;
global using System.Linq;
global using System.Net.Http;
global using System.Threading;
global using System.Threading.Tasks;
Seven namespaces, and no more. A name that is not in them, such as StringBuilder from System.Text or Regex from System.Text.RegularExpressions, still needs its own using. The setting saves the common lines, not every line.
global using
The generated file uses global using, which imports a namespace for every file of the project. A project may write its own in any file it likes, usually one file called GlobalUsings.cs:
global using System.Globalization;
global using Pricing = Shop.Pricing;
With that file in the project every other file writes CultureInfo and Pricing without a directive. It is the project-wide version of the same idea, and it is best kept to a handful of lines: a reader who opens one file cannot see where a name came from.
Turning ImplicitUsings off
The setting lives in the project file, and a project that wants the old style turns it off:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>disable</ImplicitUsings>
</PropertyGroup>
</Project>
With that project, the program below needs its first three lines and does not compile without them: Console is unknown, List<T> is unknown and Path is unknown, each with CS0103 or CS0246. The same four statements with the directives written out:
using System;
using System.Collections.Generic;
using System.IO;
var names = new List<string> { "Ada", "Grace", "Linus" };
Console.WriteLine(string.Join(", ", names));
Console.WriteLine(Path.Combine("logs", "app.txt"));
dotnet run
Ada, Grace, Linus
logs/app.txt
Both forms compile in this project, which keeps the setting on: an explicit using of a namespace that is already global is allowed and prints no warning. That is why a page can show the explicit lines while the project stays in the modern style.
Exercises
- Put the Program class of the first program into namespace Shop.Orders; and call it from a second file by its full name. Which prefix does the second file need?
- Add using Text = System.Text; to the first program and write Text.StringBuilder. Which line changed?
- Turn ImplicitUsings off and build the four-statement program. Write down the exact error of the first missing namespace.
- Add a GlobalUsings.cs with global using System.Text; and drop the local using of the first program. Does it still build?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does the using directive do at compile time?
Answer
It lets the file use short type names of that namespace
A using only saves the prefix in the source; which assemblies are referenced is decided by the project file.
-
How many namespaces does ImplicitUsings add to a console project?
Answer
Seven: System, Collections.Generic, IO, Linq, Net.Http, Threading and Threading.Tasks
The generated GlobalUsings file lists exactly seven global using lines, and a namespace outside them still needs its own directive.
-
What does this program print?
var names = new List<string> { "Ada", "Grace" }; Console.WriteLine(string.Join("-", names));Answer
Ada-Grace
string.Join puts the separator between the items, and System.Collections.Generic is implicit, so List needs no using.
-
Which namespace must a file import to write Regex without a prefix?
Answer
System.Text.RegularExpressions
Regex lives in System.Text.RegularExpressions, which is not one of the seven implicit namespaces.
-
What does this program print?
namespace Shop; class Program { static void Main() => Console.WriteLine(typeof(Program).FullName); }Answer
Shop.Program
A file-scoped namespace covers the whole file, so the class is Shop.Program, and FullName prints both parts.
-
What does
using Text = System.Text;declare?Answer
An alias, so the file writes Text.StringBuilder
The form with = is an alias for one namespace or type, valid inside the file that declares it.
-
What does this program print?
Console.WriteLine(Path.Combine("a", "b.txt")); Console.WriteLine(Path.GetExtension("b.txt"));Answer
a/b.txt / .txt
Combine joins the two parts with the separator of the system, which is a slash on Linux, and GetExtension keeps the dot.
-
What happens when a file uses Console in a project with ImplicitUsings disabled and no using line?
Answer
The build fails: the name Console does not exist in the current context
Without the implicit using and without using System, the compiler cannot resolve Console and reports CS0103.
-
What does a global using in one file of a project do?
Answer
It imports the namespace for every file of the project
global using is the project-wide form the generated GlobalUsings file uses, and it applies to every file that is compiled with it.
-
What does this program print?
using System.Text; var sb = new StringBuilder(); sb.Append("ab").Append("cd"); Console.WriteLine(sb.Length);Answer
4
Two appends of two characters leave four in the builder, and Length prints the count rather than the text.
The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev