Direttiva using e namespace in C#: alias, using static, global using

Ogni tipo in .NET ha un nome completo formato da un namespace e dal nome del tipo: System.Console, System.Collections.Generic.List<T>, System.Text.StringBuilder. I namespace raggruppano tipi correlati ed evitano i conflitti di nomi, così la tua classe Order o Timer può convivere con quelle delle librerie. La direttiva using in cima a un file importa un namespace, così puoi usare i nomi brevi.

using System;
using System.Collections.Generic;
using System.Text;

class Program
{
    static void Main()
    {
        // With the using directives:
        var cart = new List<string> { "tea", "honey" };
        var sb = new StringBuilder();
        sb.Append("Cart: ").Append(string.Join(", ", cart));
        Console.WriteLine(sb.ToString());

        // The same thing with fully qualified names, no directives needed:
        var cart2 = new System.Collections.Generic.List<string> { "milk" };
        System.Console.WriteLine(cart2.Count);
    }
}

Output:

Cart: tea, honey
1

Una direttiva using agisce solo sui nomi in fase di compilazione. Non carica una libreria né aggiunge codice al programma; quali librerie sono disponibili lo decidono i riferimenti del progetto e i pacchetti NuGet. Se il compilatore segnala che un tipo o un namespace "could not be found (are you missing a using directive or an assembly reference?)", errore CS0246, manca la riga using oppure il pacchetto non è referenziato.

Dichiarare i tuoi namespace

Metti i tipi dentro un blocco namespace. I namespace si possono annidare, si scrivono con i punti e lo stesso namespace può essere distribuito su molti file.

using System;

namespace Shop.Billing
{
    class Invoice
    {
        public decimal Amount = 120.00m;
    }
}

namespace Shop.Shipping
{
    class Invoice   // same name, different namespace: no clash
    {
        public string Carrier = "DHL";
    }
}

namespace Shop
{
    class Program
    {
        static void Main()
        {
            var bill = new Billing.Invoice();        // relative to Shop
            var label = new Shop.Shipping.Invoice(); // full name
            Console.WriteLine($"{bill.Amount:F2} via {label.Carrier}");
            Console.WriteLine(typeof(Billing.Invoice).FullName);
        }
    }
}

Output:

120.00 via DHL
Shop.Billing.Invoice

namespace Shop.Billing { } è una scorciatoia per namespace Shop { namespace Billing { } }. Il codice dentro Shop può riferirsi a Billing.Invoice senza il prefisso Shop., perché i nomi vengono cercati prima nei namespace che li contengono.

Convenzioni: inizia con l'azienda o il prodotto (Contoso.Payments), poi la funzionalità o il livello, e rispecchia la struttura delle cartelle (Contoso.Payments/Refunds/RefundService.cs contiene Contoso.Payments.Refunds). Non dare mai a una classe lo stesso nome del suo namespace (Shop.Shop), perché costringe a qualificazioni scomode ovunque.

Alias

using Name = Namespace.Type; dà a un tipo (o a un namespace) un nome locale. Serve in due situazioni: accorciare un tipo generico lungo e risolvere un conflitto.

using System;
using System.Collections.Generic;
using PriceTable = System.Collections.Generic.Dictionary<string, decimal>;
using Col = System.Collections.Generic;

class Program
{
    static void Main()
    {
        var prices = new PriceTable
        {
            ["espresso"] = 2.40m,
            ["latte"] = 3.60m
        };
        Console.WriteLine($"latte: {prices["latte"]:F2}");

        var queue = new Col.Queue<string>();
        queue.Enqueue("order 17");
        Console.WriteLine(queue.Peek());
    }
}

Output:

latte: 3.60
order 17

Gli alias valgono solo nel file in cui sono dichiarati (a meno che non siano global, vedi sotto). Da C# 12 un alias può indicare qualsiasi tipo, comprese tuple e array: using Point = (int X, int Y);.

Riferimenti ambigui (CS0104)

Quando due namespace importati contengono un tipo con lo stesso nome, usare il nome breve è un errore. Il caso classico è Timer, che esiste in System.Threading, System.Timers e (nelle applicazioni desktop) System.Windows.Forms:

using System.Threading;
using System.Timers;

var t = new Timer(1000);
// error CS0104: 'Timer' is an ambiguous reference between
// 'System.Timers.Timer' and 'System.Threading.Timer'

Tre soluzioni, dalla più locale alla meno locale: scrivi il nome completo (new System.Timers.Timer(1000)), aggiungi un alias che dica quale intendi oppure rimuovi la direttiva che non ti serve.

using System;
using System.Threading;
using System.Timers;
using Timer = System.Timers.Timer;   // "Timer" now means this one

class Program
{
    static void Main()
    {
        var timer = new Timer(250);
        Console.WriteLine(timer.Interval);
        Console.WriteLine(timer.GetType().FullName);

        // The other Timer is still reachable by its full name:
        Console.WriteLine(typeof(System.Threading.Timer).FullName);
        timer.Dispose();
    }
}

Output:

250
System.Timers.Timer
System.Threading.Timer

Se il tuo namespace definisce un tipo chiamato System o Console, il prefisso global:: forza la ricerca a partire dalla radice: global::System.Console.WriteLine("hi");. Il codice generato lo usa ovunque proprio per questo motivo.

using static

using static importa i membri statici di un singolo tipo, così si possono chiamare senza il nome del tipo. È adatto al codice che chiama la stessa classe più e più volte, come Math:

using System;
using static System.Math;
using static System.Console;

class Program
{
    static void Main()
    {
        double radius = 3;
        double area = PI * Pow(radius, 2);
        WriteLine($"Area: {area:F2}");
        WriteLine($"Hypotenuse: {Sqrt(3 * 3 + 4 * 4)}");
        WriteLine(Max(17, 42));
    }
}

Output:

Area: 28.27
Hypotenuse: 5
42

using static funziona anche con gli enum (using static System.DayOfWeek; ti permette di scrivere Monday) e con le tue classi statiche. Usalo dove i nomi brevi restano non ambigui; un WriteLine da solo in un file grande può lasciare chi legge a chiedersi di quale writer si tratti.

global using e namespace con ambito di file (C# 10)

Due funzionalità di C# 10 riducono il codice ripetitivo in cima ai file. Un global using vale per tutti i file del progetto, e di solito si tiene in un unico file come GlobalUsings.cs:

// GlobalUsings.cs, C# 10 and later
global using System;
global using System.Collections.Generic;
global using System.Linq;
global using Money = System.Decimal;

I progetti SDK su .NET 6 e successivi possono generarli per te. Con <ImplicitUsings>enable</ImplicitUsings> nel .csproj (il default nei nuovi template), un progetto console riceve System, System.Collections.Generic, System.IO, System.Linq, System.Net.Http, System.Threading e System.Threading.Tasks; i progetti web ricevono anche i namespace di ASP.NET Core. Ecco perché i file Program.cs moderni iniziano direttamente con il codice.

Un namespace con ambito di file dichiara il namespace per tutto il file con un punto e virgola invece di un blocco, risparmiando un livello di indentazione:

// C# 10 and later
namespace Shop.Billing;

public class Invoice
{
    public decimal Amount { get; set; }
}

Un file può avere un solo namespace con ambito di file, e non si può mescolare con namespace a blocco nello stesso file. I progetti più vecchi, gli script Unity e il codice che punta a .NET Framework usano la forma a blocco vista prima.

Dove vanno le direttive using, e l'istruzione using

Le direttive using devono venire prima di qualsiasi dichiarazione di namespace o di tipo nel file (i global using prima di tutto il resto). Si possono anche mettere dentro un blocco namespace, e in quel caso valgono solo lì; le guide di stile non sono d'accordo, e la maggior parte del codice .NET le tiene in cima.

La parola chiave using ha un secondo compito, senza relazione con il primo, dentro i metodi: l'istruzione using using (var file = File.OpenRead(path)) { ... } chiama Dispose sull'oggetto quando il blocco finisce, chiudendo file e connessioni. Condivide la parola chiave e nient'altro. Vedi la pagina sull'istruzione using.