Extern Alias

An extern alias is a C# language feature that introduces a distinct root-level identifier for an external assembly. It allows the compiler to disambiguate between types that share the exact same fully qualified name (identical namespaces and type names) but reside in different referenced assemblies. By mapping an assembly to an external alias, the assembly’s global namespace is nested under the specified alias rather than the default global:: namespace.

Syntax and Declaration

An extern alias directive can be declared at the root of a compilation unit (file) or within a namespace body. In either context, the directive must precede all using directives and member declarations within that specific scope.

To access types within the aliased assembly, you use the namespace alias qualifier operator (::).

// File-scoped extern alias declaration
extern alias LibraryV1;

using System;
using LegacyGrid = LibraryV1::Controls.DataGrid;

namespace Application
{
    // Namespace-scoped extern alias declaration
    extern alias LibraryV2;
    
    using ModernGrid = LibraryV2::Controls.DataGrid;

    public class GridManager
    {
        public void InitializeGrids()
        {
            // Instantiation via the using alias
            LegacyGrid oldGrid = new LegacyGrid();
            
            // Inline instantiation using the extern alias directly
            LibraryV2::Controls.DataGrid newGrid = new LibraryV2::Controls.DataGrid();
        }
    }
}

Compiler Configuration

The extern alias directive in code requires an explicit mapping between the alias identifier used in the source code and the physical assembly file during compilation.

MSBuild (.csproj) Integration

In modern .NET project files, the mapping is defined using the <Aliases> metadata tag within an assembly <Reference> or <PackageReference> node.

<ItemGroup>
  <Reference Include="Controls.Library.V1">
    <HintPath>..\lib\v1\Controls.Library.dll</HintPath>
    <Aliases>LibraryV1</Aliases>
  </Reference>
  
  <Reference Include="Controls.Library.V2">
    <HintPath>..\lib\v2\Controls.Library.dll</HintPath>
    <Aliases>LibraryV2</Aliases>
  </Reference>
</ItemGroup>

Command-Line Compiler (csc.exe)

If invoking the C# compiler directly, the alias is passed via the /reference (or /r) flag, appending the alias name and an equals sign before the assembly path.

csc /reference:LibraryV1=v1\Controls.Library.dll /reference:LibraryV2=v2\Controls.Library.dll Program.cs

Technical Characteristics

• The global Context: By default, all referenced assemblies are implicitly merged into the global alias. When you assign a custom alias to an assembly, it is removed from the global namespace unless you explicitly declare multiple aliases for it (e.g., <Aliases>global,LibraryV1</Aliases>).
• Scope: The scope of an extern alias directive depends on its declaration location. If declared at the root of a compilation unit, it is file-scoped. If declared within a namespace block, it is namespace-scoped and applies only to declarations within that specific namespace body.
• Resolution Hierarchy: The compiler resolves the identifier on the left side of the :: operator by first checking for extern alias declarations, ensuring that the alias root takes precedence over identically named namespaces within the current project.

Master C# with Deep Grasping Methodology!

Learn More