C# Using Alias Directive

The using alias directive creates a user-defined identifier for an existing namespace or type. It instructs the C# compiler to substitute the alias with the target namespace or type during the compilation process. This substitution is strictly a compile-time mechanism; aliases do not create new types and do not exist in the emitted Intermediate Language (IL).

Syntax

using alias_name = namespace_or_type_name;

Scope and Modifiers

Compilation Unit Scope: When declared at the top of a file, preceding any namespace or type declarations, the alias is scoped to the entire compilation unit (the specific source file).
Namespace Scope: When declared inside a block-scoped namespace { ... } declaration, the alias is scoped only to that specific namespace body. It must be placed at the top of the namespace body, before any type or nested namespace declarations.
Global Scope (C# 10+): Applying the global modifier extends the alias to the entire compilation (all compilation units within the project or assembly). Global aliases must precede any non-global using directives.

global using alias_name = namespace_or_type_name;

Resolution Rules

The right-hand side of the alias assignment is resolved relative to the declaration space containing the using directive. It is resolved as if the containing file or namespace had no other using directives to assist in resolution. It does not need to be fully qualified from the root namespace, but it cannot implicitly rely on imported namespaces.

// Invalid: Cannot rely on a separate 'using System.Collections.Generic;'
// using StringMap = Dictionary<string, string>; 

// Valid: Explicitly pathed because it cannot rely on other using directives
using StringMap = System.Collections.Generic.Dictionary<string, string>;

namespace MyCompany.Core
{
    // Valid: Resolves relative to the MyCompany.Core declaration space.
    // Must precede all other elements (like namespaces or classes) in the body.
    using LogUtil = Utilities.Logger;

    namespace Utilities
    {
        class Logger { }
    }
}

Supported Alias Targets

1. Namespace Aliasing Maps an identifier to a specific namespace hierarchy.

using NetHttp = System.Net.Http;

2. Constructed Type Aliasing Maps an identifier to a specific, fully constructed type. Open generics (e.g., List<>) cannot be aliased.

using UserCache = System.Collections.Concurrent.ConcurrentDictionary<int, string>;

3. Any Type Aliasing (C# 12+) Starting in C# 12, the directive supports aliasing virtually any valid C# type, including tuples, arrays, pointer types, and function pointers.

// Tuple alias
using Point3D = (double X, double Y, double Z);

// Array alias
using Matrix = double[][];

// Unsafe pointer alias
using IntPointer = int*;

// Function pointer alias
using ActionDelegate = delegate*<int, void>;

The Namespace Alias Qualifier (`::`)

When an alias shares a name with a locally declared type or namespace, the compiler may encounter an ambiguity error. The namespace alias qualifier operator (::) forces the compiler to resolve the identifier specifically against the defined alias rather than the local scope.

using Sys = System;

class Program
{
    static void Main()
    {
        // Forces resolution through the 'Sys' alias
        Sys::Console.WriteLine("Resolved via alias qualifier.");
    }
}