Diretiva using e namespaces em C#: aliases, using static, global using

Todo tipo no .NET tem um nome completo formado por um namespace e o nome do tipo: System.Console, System.Collections.Generic.List<T>, System.Text.StringBuilder. Os namespaces agrupam tipos relacionados e evitam conflitos de nomes, então a sua própria classe Order ou Timer pode coexistir com as das bibliotecas. A diretiva using no topo de um arquivo importa um namespace para que você possa usar os nomes curtos.

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);
    }
}

Saída:

Cart: tea, honey
1

Uma diretiva using só afeta nomes em tempo de compilação. Ela não carrega uma biblioteca nem adiciona código ao programa; quais bibliotecas estão disponíveis é decidido pelas referências do projeto e pelos pacotes NuGet. Se o compilador informa que um tipo ou namespace "could not be found (are you missing a using directive or an assembly reference?)", erro CS0246, ou falta a linha using ou o pacote não está referenciado.

Declarando seus próprios namespaces

Coloque os tipos dentro de um bloco namespace. Namespaces podem ser aninhados, escritos com pontos, e o mesmo namespace pode estar espalhado por muitos arquivos.

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);
        }
    }
}

Saída:

120.00 via DHL
Shop.Billing.Invoice

namespace Shop.Billing { } é uma abreviação de namespace Shop { namespace Billing { } }. Código dentro de Shop pode se referir a Billing.Invoice sem o prefixo Shop., porque os nomes são procurados primeiro nos namespaces que os contêm.

Convenções: comece com a empresa ou o produto (Contoso.Payments), depois o recurso ou a camada, e siga a estrutura de pastas (Contoso.Payments/Refunds/RefundService.cs contém Contoso.Payments.Refunds). Nunca dê a uma classe o mesmo nome do seu namespace (Shop.Shop), o que obriga a qualificações estranhas em todo lugar.

Aliases

using Name = Namespace.Type; dá a um tipo (ou a um namespace) um nome local. Duas situações pedem isso: encurtar um tipo genérico longo e resolver um conflito.

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());
    }
}

Saída:

latte: 3.60
order 17

Aliases só valem no arquivo em que são declarados (a menos que sejam global, abaixo). No C# 12 em diante, um alias pode nomear qualquer tipo, inclusive tuplas e arrays: using Point = (int X, int Y);.

Referências ambíguas (CS0104)

Quando dois namespaces importados contêm um tipo com o mesmo nome, usar o nome curto é um erro. O caso clássico é Timer, que existe em System.Threading, em System.Timers e (em apps desktop) em 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'

Três soluções, da mais local para a menos local: escrever o nome totalmente qualificado (new System.Timers.Timer(1000)), adicionar um alias que diz qual você quer, ou remover a diretiva de que você não precisa.

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();
    }
}

Saída:

250
System.Timers.Timer
System.Threading.Timer

Se o seu próprio namespace define um tipo chamado System ou Console, o prefixo global:: força a busca a partir da raiz: global::System.Console.WriteLine("hi");. Código gerado o usa em todo lugar por esse motivo.

using static

using static importa os membros static de um único tipo, para que eles possam ser chamados sem o nome do tipo. Ele combina com código que chama a mesma classe várias e várias vezes, como 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));
    }
}

Saída:

Area: 28.27
Hypotenuse: 5
42

using static também funciona com enums (using static System.DayOfWeek; permite escrever Monday) e com suas próprias classes static. Use-o onde os nomes curtos continuam sem ambiguidade; WriteLine sozinho em um arquivo grande pode deixar o leitor se perguntando de qual writer se trata.

global using e namespaces com escopo de arquivo (C# 10)

Dois recursos do C# 10 cortam a repetição no topo dos arquivos. Um global using vale para todos os arquivos do projeto e normalmente fica em um único arquivo, como 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;

Projetos SDK do .NET 6 em diante podem gerar isso para você. Com <ImplicitUsings>enable</ImplicitUsings> no .csproj (o padrão nos templates novos), um projeto de console recebe System, System.Collections.Generic, System.IO, System.Linq, System.Net.Http, System.Threading e System.Threading.Tasks; projetos web recebem também namespaces do ASP.NET Core. É por isso que os arquivos Program.cs modernos começam direto com código.

Um namespace com escopo de arquivo declara o namespace para o arquivo inteiro com um ponto e vírgula em vez de um bloco, economizando um nível de indentação:

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

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

Um arquivo só pode ter um namespace com escopo de arquivo, e ele não pode ser misturado com namespaces em bloco no mesmo arquivo. Projetos mais antigos, scripts Unity e código para .NET Framework usam a forma em bloco mostrada antes.

Onde ficam as diretivas using, e a instrução using

As diretivas using precisam vir antes de qualquer declaração de namespace ou de tipo no arquivo (os global usings antes de tudo). Elas também podem ser colocadas dentro de um bloco de namespace, e nesse caso só valem ali; os guias de estilo divergem, e a maior parte do código .NET as mantém no topo.

A palavra-chave using tem um segundo trabalho, sem relação, dentro dos métodos: a instrução using using (var file = File.OpenRead(path)) { ... } chama Dispose no objeto quando o bloco termina, fechando arquivos e conexões. Elas compartilham a palavra-chave e nada mais. Veja a página da instrução using.