Skip to content

Commit aabcfd7

Browse files
BillWagnerCopilotgewarren
authored
Provide benefits for using alternatives (#54000)
* 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. * Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * respond to feedback. * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Bill Wagner <wiwagn@microsoft.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
1 parent 87b99d7 commit aabcfd7

1 file changed

Lines changed: 9 additions & 6 deletions

File tree

docs/csharp/fundamentals/program-structure/namespaces.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -52,38 +52,41 @@ File-scoped namespaces reduce nesting and make files easier to read. You can onl
5252
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.
5353

5454
> [!IMPORTANT]
55-
> 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.
55+
> It's rare to declare more than one namespace in the same file. The more common scenario is to use *file-scoped* namespaces.
5656
5757
The following snippet is an example of a *block-scoped* namespace:
5858

5959
:::code language="csharp" source="snippets/namespaces/BlockScoped.cs" id="BlockScopedNamespace":::
6060

6161
## Using directives
6262

63-
Without a `using` directive, you must refer to every type by its *fully qualified name*, the complete namespace path plus the type name:
63+
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:
6464

6565
:::code language="csharp" source="snippets/namespaces/Basics.cs" id="FullyQualifiedName":::
6666

67-
A `using` directive at the top of a file imports a namespace so you can use its types by their simple names:
67+
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:
6868

6969
:::code language="csharp" source="snippets/namespaces/Basics.cs" id="UsingDirective":::
7070

7171
For more information, see the [`using` directive](../../language-reference/keywords/using-directive.md).
7272

7373
### Global using directives
7474

75-
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:
75+
A `using` directive only applies to the file it appears in. Instead of repeating the same `using` directives in every file, use *global using* directives, which let you declare them once for your entire project. Place them in any file. Many teams create a dedicated `GlobalUsings.cs` file:
7676

7777
:::code language="csharp" source="snippets/namespaces/GlobalUsings.cs" id="GlobalUsings":::
7878

79-
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.
79+
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.
8080

8181
### Implicit usings
8282

83-
The .NET SDK automatically generates global using directives for the most common namespaces based on your project type. Enable implicit usings by setting `<ImplicitUsings>enable</ImplicitUsings>` 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`.
83+
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 `<ImplicitUsings>enable</ImplicitUsings>` in your project file. For example, a console app project automatically imports <xref:System?displayProperty=fullName>, <xref:System.Collections.Generic?displayProperty=fullName>, <xref:System.IO?displayProperty=fullName>, <xref:System.Linq?displayProperty=fullName>, <xref:System.Threading?displayProperty=fullName>, and <xref:System.Threading.Tasks?displayProperty=fullName>. New projects that you create with `dotnet new` enable `ImplicitUsings` by default. New files start clean, with no boilerplate `using` directives for everyday types like <xref:System.Console>, <xref:System.Collections.Generic.List`1>, or <xref:System.Threading.Tasks.Task>.
8484

8585
For more information, see [Implicit using directives](../../../core/project-sdk/overview.md#implicit-using-directives).
8686

87+
> [!NOTE]
88+
> 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<T>` by their simple names.
89+
8790
### Static using directives
8891

8992
A `static using` directive imports the static members of a type so you can call them without the type name prefix:

0 commit comments

Comments
 (0)