From d71107c08161683083ef4a629753865c8d9eb4fc Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 22 May 2026 11:20:09 -0400 Subject: [PATCH 1/3] Provide benefits for `using` alternatives Fixes #52871 I didn't add the explicit usings throughout the article. Instead, I added mores text to take the reader on a journey explaining the benefits of each of the alternatives. Finally, add a note that most of the samples in our docs assume the implicit usings are in place. --- .../fundamentals/program-structure/namespaces.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/csharp/fundamentals/program-structure/namespaces.md b/docs/csharp/fundamentals/program-structure/namespaces.md index 7ca3f6f2a5432..3fdd5fb6ce25b 100644 --- a/docs/csharp/fundamentals/program-structure/namespaces.md +++ b/docs/csharp/fundamentals/program-structure/namespaces.md @@ -52,7 +52,7 @@ File-scoped namespaces reduce nesting and make files easier to read. You can onl Use *block-scoped* syntax when you need to declare more than one namespace in the same file. This style adds an extra level of indentation. > [!IMPORTANT] -> It's considered bad-practice to declare more than one namespace in the same file. The more common scenario is to use *file-scoped* namespaces. +> It's rare to declare more than one namespace in the same file. The more common scenario is to use *file-scoped* namespaces. The following snippet is an example of a *block-scoped* namespace: @@ -60,11 +60,11 @@ The following snippet is an example of a *block-scoped* namespace: ## Using directives -Without a `using` directive, you must refer to every type by its *fully qualified name*, the complete namespace path plus the type name: +Without a `using` directive, you must refer to every type by its *fully qualified name*, the complete namespace path plus the type name. This style is verbose, repetitive, and harder to read, especially when a file uses many types from the same namespace: :::code language="csharp" source="snippets/namespaces/Basics.cs" id="FullyQualifiedName"::: -A `using` directive at the top of a file imports a namespace so you can use its types by their simple names: +A `using` directive at the top of a file imports a namespace so you can use its types by their simple names. The directive appears once, and every reference in the file becomes shorter and easier to read: :::code language="csharp" source="snippets/namespaces/Basics.cs" id="UsingDirective"::: @@ -72,18 +72,21 @@ For more information, see the [`using` directive](../../language-reference/keywo ### Global using directives -If you write the same `using` directives in every file, *global using* directives let you declare them once for your entire project. Place them in any file. Many teams create a dedicated `GlobalUsings.cs` file: +A `using` directive only applies to the file it appears in. When you write the same `using` directives in every file, *global using* directives let you declare them once for your entire project. Place them in any file. Many teams create a dedicated `GlobalUsings.cs` file: :::code language="csharp" source="snippets/namespaces/GlobalUsings.cs" id="GlobalUsings"::: -After declaring a global using, every file in the project can refer to types from that namespace by using simple names without an additional `using` directive. +After declaring a global using, every file in the project can refer to types from that namespace by their simple names without an additional `using` directive. Global usings remove repetition across files, shrink the `using` block at the top of each file, and centralize namespace policy for the project. ### Implicit usings -The .NET SDK automatically generates global using directives for the most common namespaces based on your project type. Enable implicit usings by setting `enable` in your project file. For example, a console app project automatically imports `System`, `System.Collections.Generic`, `System.IO`, `System.Linq`, `System.Threading`, and `System.Threading.Tasks`. The current SDK enables `ImplicitUsings` when you create a new project by using `dotnet new`. +For the most common namespaces, you don't have to write any `using` directives at all. The .NET SDK automatically generates global using directives based on your project type. Enable implicit usings by setting `enable` in your project file. For example, a console app project automatically imports , , , , , and . The current SDK enables `ImplicitUsings` when you create a new project by using `dotnet new`. New files start clean, with no boilerplate `using` block for everyday types like , , or . For more information, see [Implicit using directives](../../../core/project-sdk/overview.md#implicit-using-directives). +> [!NOTE] +> The other code samples in this article, and most samples throughout the .NET docs, assume that implicit usings (or the equivalent global usings for the workload) are enabled. That's why you don't see `using System;` and similar directives at the top of each snippet, even though the code uses types like `Console` or `List` by their simple names. + ### Static using directives A `static using` directive imports the static members of a type so you can call them without the type name prefix: From 7a386cf275143d28263d028b6be70df5277cdce1 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 22 May 2026 11:44:58 -0400 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/csharp/fundamentals/program-structure/namespaces.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/csharp/fundamentals/program-structure/namespaces.md b/docs/csharp/fundamentals/program-structure/namespaces.md index 3fdd5fb6ce25b..122922b9eb031 100644 --- a/docs/csharp/fundamentals/program-structure/namespaces.md +++ b/docs/csharp/fundamentals/program-structure/namespaces.md @@ -64,7 +64,7 @@ Without a `using` directive, you must refer to every type by its *fully qualifie :::code language="csharp" source="snippets/namespaces/Basics.cs" id="FullyQualifiedName"::: -A `using` directive at the top of a file imports a namespace so you can use its types by their simple names. The directive appears once, and every reference in the file becomes shorter and easier to read: +A `using` directive at the top of a file imports a namespace so you can use its types by their simple names. The following snippet shows the shorter type usage after that import, which keeps references throughout the file shorter and easier to read: :::code language="csharp" source="snippets/namespaces/Basics.cs" id="UsingDirective"::: @@ -80,7 +80,7 @@ After declaring a global using, every file in the project can refer to types fro ### Implicit usings -For the most common namespaces, you don't have to write any `using` directives at all. The .NET SDK automatically generates global using directives based on your project type. Enable implicit usings by setting `enable` in your project file. For example, a console app project automatically imports , , , , , and . The current SDK enables `ImplicitUsings` when you create a new project by using `dotnet new`. New files start clean, with no boilerplate `using` block for everyday types like , , or . +For the most common namespaces, you don't have to write any `using` directives at all. The .NET SDK automatically generates global using directives based on your project type. Enable implicit usings by setting `enable` in your project file. For example, a console app project automatically imports , , , , , and . New projects that you create with `dotnet new` enable `ImplicitUsings` by default. New files start clean, with no boilerplate `using` block for everyday types like , , or . For more information, see [Implicit using directives](../../../core/project-sdk/overview.md#implicit-using-directives). From 28dfb4a415551a154b33ea555a98911b7a91ac4e Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 22 May 2026 11:46:19 -0400 Subject: [PATCH 3/3] respond to feedback. --- docs/csharp/fundamentals/program-structure/namespaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/csharp/fundamentals/program-structure/namespaces.md b/docs/csharp/fundamentals/program-structure/namespaces.md index 122922b9eb031..79741dcf7d29a 100644 --- a/docs/csharp/fundamentals/program-structure/namespaces.md +++ b/docs/csharp/fundamentals/program-structure/namespaces.md @@ -85,7 +85,7 @@ For the most common namespaces, you don't have to write any `using` directives a For more information, see [Implicit using directives](../../../core/project-sdk/overview.md#implicit-using-directives). > [!NOTE] -> The other code samples in this article, and most samples throughout the .NET docs, assume that implicit usings (or the equivalent global usings for the workload) are enabled. That's why you don't see `using System;` and similar directives at the top of each snippet, even though the code uses types like `Console` or `List` by their simple names. +> The other code samples in this article, and most samples throughout the .NET docs, assume that implicit usings (or the equivalent global usings for the project type) are enabled. That's why you don't see `using System;` and similar directives at the top of each snippet, even though the code uses types like `Console` or `List` by their simple names. ### Static using directives