Local Functions

C# 7.0 introduced the ability to declare functions within methods. In other words, rather than always declaring a method within a class, the method (technically a function) could be declared within another method (see Listing 5.7).

Listing 5.7: Declaring a Local Function
1. public static void Main()
2. {
3.     string GetUserInput(string prompt)
4.     {
5.         string? input;
6.         do
7.         {
8.             Console.Write(prompt + ": ");
9.             input = Console.ReadLine();
10.         }
11.         while(string.IsNullOrWhiteSpace(input));
12.         return input!;
13.     };
14.     
15.     string firstName = GetUserInput("First Name");
16.     string lastName = GetUserInput("Last Name");
17.     string email = GetUserInput("Email Address");
18.  
19.     Console.WriteLine($"{firstName} {lastName} <{email}>");
20.     //...

This language construct is called a local function. The reason to declare it like this is that the function’s scope is limited to invocation from within the method where it is declared. Outside of the method’s scope, it is not possible to call the local function. In addition, the local function can access local variables in the method that are declared before the local function. Alternatively, this can explicitly be prevented by adding the static to the beginning of the local function declaration (see “Static Anonymous Functions” in Chapter 13).

Using Directives

Fully qualified namespace names can become quite long and unwieldy. It is possible, however, to import all the types from one or more namespaces so that they can be used without full qualification.

Using Directive Overview

Rather than a declarative that applies to the entire project, C# includes a using directive that applies only to the current file. For example, Listing 5.8 (with Output 5.2) doesn’t prefix RegEx with System.Text.RegularExpressions. The namespace may be omitted because of the using System.Text.RegularExpressions directive that appears at the top of the listing.

Listing 5.8: Using Directive Example
1. // The using directive imports all types from the 
2. // specified namespace into the entire file
3. using System.Text.RegularExpressions;
4.  
5. public class Program
6. {
7.     public static void Main()
8.     {
9.         const string firstName = "FirstName";
10.         const string initial = "Initial";
11.         const string lastName = "LastName";
12.  
13.         // Explaining regular expressions is beyond the
14.         // scope of this book.
15.         // See https://www.regular-expressions.info/ for
16.         // more information.
17.         const string pattern = $"""
18.             (?<{firstName}>\w+)\s+((?<{
19.             initial}>\w)\.\s+)?(?<{
20.             lastName}>\w+)\s*
21.             """;
22.  
23.         Console.WriteLine(
24.             "Enter your full name (e.g. Inigo T. Montoya): ");
25.         string name = Console.ReadLine()!;
26.  
27.         // No need to qualify RegEx type with
28.         // System.Text.RegularExpressions because
29.         // of the using directive above
30.         Match match = Regex.Match(name, pattern);
31.  
32.         if (match.Success)
33.         {
34.             Console.WriteLine(
35.                 $"{firstName}: {match.Groups[firstName]}");
36.             Console.WriteLine(
37.                 $"{initial}: {match.Groups[initial]}");
38.             Console.WriteLine(
39.                 $"{lastName}: {match.Groups[lastName]}");
40.         }
41.     }
42. }
Output 5.2
Hello, my name is Inigo Montoya

A using directive such as using System.Text does not enable you to omit System.Text from a type declared within a nested namespace such as System.Text.RegularExpressions. For example, if your code accessed the RegEx type from the System.Text.RegularExpressions namespace, you would have to either include an additional using System.Text.RegularExpressions directive or fully qualify the type as System.Text.RegularExpressions.RegEx, not just RegularExpressions.RegEx. In short, a using directive does not import types from any nested namespaces. Nested namespaces, which are identified by the period in the namespace, always need to be imported explicitly.

Language Contrast: Java—Wildcards in the import Directive

Java enables importing namespaces using a wildcard such as the following:

import javax.swing.*;

In contrast, C# does not support a wildcard using directive but instead requires each namespace to be imported explicitly.

Frequent use of types within a particular namespace implies that the addition of a using directive for that namespace is a good idea, instead of fully qualifying all types within the namespace. Accordingly, almost all C# files include the using System directive at the top. Throughout the remainder of this book, code listings often omit the using System directive from the manuscript. Other namespace directives are generally included explicitly, however.

One interesting effect of the using System directive is that the string data type can be identified with varying case: String or string. The former version relies on the using System directive, and the latter uses the string keyword. Both are valid C# references to the System.String data type, and the resultant Common Intermediate Language (CIL) code is unaffected by which version is chosen.

Beginner Topic
Namespaces

As described earlier, namespaces are an organizational mechanism for categorizing and grouping together related types. Developers can discover related types by examining other types within the same namespace as a familiar type. Additionally, through namespaces, two or more types may have the same name as long as they are disambiguated by different namespaces.

Implicit Using Directives

Readers will recall from Chapter 1 there was an ImplicitUsings element within the .csproj file for C# 10.0 and later:

<ImplicitUsings>enable</ImplicitUsings>

In addition, the source code consistently refers to things like Console, even though the fully qualified name is System.Console. The ability to abbreviate is afforded by the ImplicitUsings element, which tells the compiler to infer the namespace automatically rather than require the programmer to provide it. Using directives, therefore, allows the use of type identifiers without specifying their fully qualified name. To accomplish this, the complier generates global using directives whenever the ImplicitUsings element is set to enable.

Global Using Directives

If you search the subdirectory of a C# 10.0 (or higher) project, you will notice there is a file with the extension .GlobalUsing.g.cs, generally found in an obj folder subdirectory, and it contains multiple global using directives such as those found in Listing 5.9.

Listing 5.9: Implicit Usings Generated Global Using Declaratives3
1. // <auto-generated/>
2. global using global::System;
3. global using global::System.Collections.Generic;
4. global using global::System.IO;
5. global using global::System.Linq;
6. global using global::System.Net.Http;
7. global using global::System.Threading;
8. global using global::System.Threading.Tasks;

Each of these lines4 is a global using directive that tells the compiler to imply the namespace qualifier for any type that appears within the namespace specified. For example, global using global::System allows implicit using directives like Console.WriteLine("Hello! My name is Inigo Montoya!") rather than the fully qualified name System.Console.WriteLine(...) because Console is defined in the System namespace.

Of course, you can provide your own global using declaratives. Say, for example, you frequently are using the System.Text.StringBuilder class (initially introduced in Chapter 2). Instead of always referring to it by the fully qualified name, you can provide a global using directive for the System.Text namespace and then just refer to the type using the abbreviation StringBuilder (see Listing 5.10), also still relying on implicit usings for System.Console.

Listing 5.10: Implicit Using Directives with StringBuilder
1. // The global using directive imports all types from
2. // the specified namespace into the project
3. global using System.Text;
4. // ...
5. public class Program
6. {
7.     public static void Main()
8.     {
9.         // See Chapter 6 for explanation of new();
10.         StringBuilder name = new();
11.  
12.         Console.WriteLine("Enter your first name: ");
13.         name.Append(Console.ReadLine()!.Trim());
14.  
15.         Console.WriteLine("Enter your middle initial: ");
16.         name.Append( $" { Console.ReadLine()!.Trim('.').Trim() }." );
17.  
18.         Console.WriteLine("Enter your last name: ");
19.         name.Append($" { Console.ReadLine()!.Trim() }");
20.  
21.         Console.WriteLine($"Hello {name}!");
22.     }
23. }

The global using directives applies to the entire project regardless of in which file it appears. And, although C# allows the same global using declarative multiple times, doing so is redundant. For this reason, it is preferable to place all the global using directives into a single file named Usings.cs by convention. Collocating them here also provides a well-known location to place them or remove such declaratives.

While global using directives apply to the entire project, C# also supports using directives that apply only to the current file. The global using declarative, however, must appear before any other (non-global) using directives, which we cover after the .csproj using element.

csproj Using Element

It is also possible to specify global using declaratives within your project (.csproj) file with a Using element, as shown in Listing 5.11

Listing 5.11: Sample .NET Console Project File with Using Element
1. <Project Sdk="Microsoft.NET.Sdk">
2.   <PropertyGroup>
3.     <OutputType>Exe</OutputType>
4.     <TargetFramework>net7.0</TargetFramework>
5.     <ImplicitUsings>enable</ImplicitUsings>
6.     <Nullable>enable</Nullable>
7.   </PropertyGroup>
8.   <ItemGroup>
9.     <Using Include="System.Net" />
10.     <Using Static="true" Include="System.Console"/>
11.   </ItemGroup>
12. </Project>

The important thing to note is that unlike the ImplicitUsings element, the Using element is a subelement to the ItemGroup element rather than the PropertyGroup element. And, given the Using element for System.Net specified, it is no longer necessary to fully qualify HttpClient, which is part of the System.Net namespace. Instead, the compiler will generate a global using System.Net directive when building the project. There is also another Using statement that includes a Static attribute on it, which we will explain further in the next section.

AdVanced Topic
Nested Using Directives

Not only can you have using directives at the top of a file, but you can also include them at the top of a namespace declaration. For example, if a new namespace, EssentialCSharp, were declared, it would be possible to add a using declarative at the top of the namespace declaration (see Listing 5.12).

Listing 5.12: Specifying the using Directive inside a Namespace Declaration
1. // The using directive imports all types from the 
2. // specified namespace into the entire file
3. using System.Text.RegularExpressions;
4.  
5. public class Program
6. {
7.     public static void Main()
8.     {
9.         // ...
10.         // No need to qualify RegEx type with
11.         // System.Text.RegularExpressions because
12.         // of the using directive above
13.         Match match = Regex.Match(name, pattern);
14.         // ...
15.     }
16. }

The difference between placing the using directive at the top of a file and placing it at the top of a namespace declaration is that the directive is active only within the namespace declaration. If the code includes a new namespace declaration above or below the EssentialCSharp declaration, the using System directive within a different namespace would not be active. Code seldom is written this way, especially given the standard practice of providing a single type declaration per file.

Using Static Directive

The using directive allows you to abbreviate a type name by omitting the namespace portion of the name—such that just the type name can be specified for any type within the stated namespace. In contrast, the using static directive allows you to omit both the namespace and the type name from any static member of the stated type. A using static System.Console directive, for example, allows you to specify WriteLine() rather than the fully qualified method name of System.Console.WriteLine(). Continuing with this example, we can update Listing 5.2 to leverage the using static System.Console directive to create Listing 5.13.

Listing 5.13: Using Static Directive
1. using static System.Console;
2.  
3. public class HeyYou
4. {
5.     public static void Main()
6.     {
7.         string firstName;
8.         string lastName;
9.  
10.         WriteLine("Hey you!");
11.  
12.         Write("Enter your first name: ");
13.         firstName = ReadLine() ?? string.Empty;
14.  
15.         Write("Enter your last name: ");
16.         lastName = ReadLine() ?? string.Empty;
17.  
18.         WriteLine(
19.             $"Your full name is { firstName } { lastName }.");
20.     }
21. }

In this case, there is no loss of readability of the code: WriteLine(), Write(), and ReadLine() all clearly relate to a console directive. In fact, one could argue that the resulting code is simpler and therefore clearer than before.

However, sometimes this is not the case. For example, if your code uses classes that have overlapping behavior names, such as an Exists() method on a file and an Exists() method on a directory, then a using static directive would reduce clarity when you invoke Exists(). Similarly, if the class you were writing had its own members with overlapping behavior names—for example, Display() and Write()—then clarity would be lost to the reader.

This ambiguity would not be allowed by the compiler. If two members with the same signature were available (through either using static directives or separately declared members), any invocation of them that was ambiguous would result in a compile error.

Note that C# 10 or later also support global static using directives such as:

global using static System.Console;

Similarly, a global using static directive can be configured in the csproj file:

<Using Static="true" Include="System.Console"/>

This is also shown in Listing 5.11.

Aliasing

Starting in C# 12.0, the using directive also allows aliasing a namespace or any type including tuples, pointers (Chapter 23), array types, and generic types (Chapter 12). An alias is an alternative name that you can use within the text to which the using directive applies. The two most common reasons for aliasing are to disambiguate two types that have the same name and to abbreviate a long name. In Listing 5.14, for example, the CountDownTimer alias is declared as a means of referring to the type System.Timers.Timer. Simply adding a using System.Timers directive will not sufficiently enable the code to avoid fully qualifying the Timer type. The reason is that System.Threading also includes a type called Timer; therefore, using just Timer within the code will be ambiguous.

Listing 5.14: Declaring a Type Alias
1. using CountDownTimer = System.Timers.Timer;
2. using StartStop = (DateTime Start, DateTime Stop);
3.  
4. public class HelloWorld
5. {
6.     public static void Main()
7.     {
8.         CountDownTimer timer;
9.         StartStop startStop;
10.  
11.         // ...
12.     }
13. }

Listing 5.14 uses an entirely new name, CountDownTimer, as the alias. It is possible, however, to specify the alias as Timer, as shown in Listing 5.15.

Listing 5.15: Declaring a Type Alias with the Same Name
1.  
2. // Declare alias Timer to refer to System.Timers.Timer to
3. // avoid code ambiguity with System.Threading.Timer
4. using Timer = System.Timers.Timer;
5.  
6. public class HelloWorld
7. {
8.     public static void Main()
9.     {
10.         Timer timer;
11.  
12.         // ...
13.     }
14. }

Because of the alias directive, “Timer” is not an ambiguous reference. Furthermore, to refer to the System.Threading.Timer type, you will have to either qualify the type or define a different alias.

Of course, C# 10 and later also support global aliasing using directives such as:

global using Timer = Timers.Timer;

And like with all other global using directives, a global using alias directive can be configured in the csproj file:

<Using Include=" System.Timers.Timer" Alias="Timer"/>

________________________________________

3. Although removed from this listing for elucidation purposes, the generated global using statements prefix the namespace with “global::” as in global using global::System. Discussion of namespace alias qualifiers appears later in the section.
4. Ignoring the comment that shows the code was generated by the compiler.
{{ snackbarMessage }}
;