Compartilhar via

Namespaces e diretivas de uso

Dica

Novo no desenvolvimento de software? Comece primeiro com os tutoriais de Introdução . Eles introduzem namespaces e using diretivas enquanto você escreve seus primeiros programas.

Experimentou em outro idioma? Os namespaces em C# funcionam de forma semelhante aos pacotes em Java ou módulos no Python. Avance para a sintaxe que você precisa.

Declarações de namespace e diretivas using são recursos de linguagem relacionados. Uma declaração de namespace coloca seus tipos em uma estrutura organizada. Um namespace agrupa tipos relacionados e impede colisões de nomenclatura. Uma using diretiva permite que seu programa consuma esses tipos pelos seus nomes simples. Você não precisa soletrar o caminho completo do namespace a cada uso.

Você já usou namespaces em todos os programas em C# que escreveu. Cada tipo .NET pertence a um namespace e cada using diretiva na parte superior de um arquivo faz referência a um. Por exemplo, Console e Math pertencem ao System namespace, portanto, seus nomes totalmente qualificados são System.Console e System.Math. Tipos de coleção como List<T> e Dictionary<TKey, TValue> pertencem a System.Collections.Generic. Uma única using diretiva para qualquer um desses namespaces permite que você se refira a todos os seus tipos por seus nomes simples. Você escreve List<T> em vez de System.Collections.Generic.List<T> em todos os lugares em que o usa.

Este artigo fornece mais informações sobre como os namespaces e using as diretivas funcionam e mostra exemplos de padrões que você já encontrou em bibliotecas do .NET.

Um namespace contém tipos. Cada tipo .NET pertence a um namespace. Por exemplo, considere System.Threading.Tasks.Task: o tipo Task pertence ao System.Threading.Tasks namespace.

É uma boa prática agrupar tipos relacionados ou semelhantes no mesmo namespace e é isso que o .NET faz com os tipos que ele fornece. O System.Collections.Generic namespace contém tipos relacionados à coleção e o System.IO namespace contém tipos relacionados à leitura e gravação de arquivos, diretórios e dados. O System namespace contém tipos fundamentais como Math, DateTimee Console.

O exemplo a seguir mostra como os namespaces funcionam em conjunto com using diretivas em um arquivo C# típico:

using System.Globalization;

namespace MyApp.Services;

class Greeter
{
    public string Greet(string name)
    {
        var culture = CultureInfo.CurrentCulture;
        return $"Hello, {name}! Culture: {culture.Name}";
    }
}

No exemplo anterior, a diretiva using significa que você pode usar o System.Globalization.CultureInfo pelo nome CultureInfo sem especificar o nome completo de System.Globalization.CultureInfo. A namespace diretiva declara que a Greeter classe faz parte do MyApp.Services namespace. Seu nome totalmente qualificado é MyApp.Services.Greeter.

Declarações de namespace

Uma declaração de namespace atribui seus tipos a um grupo nomeado. Cada tipo que você escreve deve pertencer a um namespace. O nome do namespace normalmente espelha a estrutura de pastas do seu projeto. Por exemplo, os tipos em uma Services/Payments pasta geralmente pertencem ao MyApp.Services.Payments namespace.

Namespaces usam o operador . para expressar hierarquia, como System.Collections.Generic. Os nomes do namespace devem ser nomes de identificador C# válidos.

Namespaces com escopo de arquivo

Use a sintaxe de escopo de arquivo quando todos os tipos em um arquivo pertencem ao mesmo namespace. Adicione um ponto-e-vírgula após a declaração de namespace e ele se aplica a todo o arquivo. Você não precisa de chaves extras ou indentação:

namespace MyApp.Models;

class Customer
{
    public required string Name { get; init; }
    public string? Email { get; init; }

    public override string ToString() => $"{Name} ({Email ?? "no email"})";
}

Namespaces com escopo de arquivo reduzem o aninhamento e facilitam a leitura dos arquivos. Você só pode ter uma declaração de namespace com escopo de arquivo por arquivo.

Dica

Utilize namespaces de escopo de arquivo em novos códigos. A maioria dos modelos e analisadores de código do .NET recomenda esse estilo.

Namespaces com escopo de bloco

Utilize a sintaxe com escopo de bloco quando precisar declarar mais de um namespace no mesmo arquivo. Esse estilo adiciona um nível extra de indentação.

Importante

É considerado uma má prática declarar mais de um namespace no mesmo arquivo. O cenário mais comum é utilizar namespaces com escopo de arquivo.

O snippet a seguir é um exemplo de um namespace com escopo de bloco :

namespace MyApp.Models
{
    class Product
    {
        public required string Name { get; init; }
        public decimal Price { get; init; }

        public override string ToString() => $"{Name}: {Price:C}";
    }
}

Uso de diretivas

Sem uma using diretiva, você deve se referir a cada tipo por seu nome totalmente qualificado, o caminho completo do namespace mais o nome do tipo:

static void ShowFullyQualified()
{
    // Without a using directive, use the fully qualified name:
    System.Console.WriteLine("Hello from fully qualified name!");
}

Uma using diretiva na parte superior de um arquivo importa um namespace para que você possa usar seus tipos por seus nomes simples:

static void ShowShortName()
{
    // With 'using System;' (or implicit usings enabled), use the short name:
    Console.WriteLine("Hello from short name!");
}

Para obter mais informações, consulte a using diretiva.

Diretivas de uso global

Se você escrever as mesmas using diretivas em cada arquivo, o uso global de diretivas permitirá que você as declare uma vez para todo o projeto. Coloque-os em qualquer arquivo. Muitas equipes criam um arquivo dedicado GlobalUsings.cs :

global using System.Text;
global using System.Text.Json;

Depois de declarar um uso global, cada arquivo no projeto pode se referir a tipos desse namespace usando nomes simples sem uma diretiva adicional using .

Usos implícitos

O SDK do .NET gera automaticamente o uso global de diretivas para os namespaces mais comuns com base no seu tipo de projeto. Habilite os usings implícitos definindo <ImplicitUsings>enable</ImplicitUsings> no arquivo de projeto. Por exemplo, um projeto de aplicativo de console importa automaticamente System, System.Collections.Generic, System.IO, System.Linq, System.Threading e System.Threading.Tasks. O SDK atual habilita ImplicitUsings quando você cria um novo projeto usando dotnet new.

Para obter mais informações, consulte Implicit using directives.

Diretivas de uso estático

Uma static using diretiva importa os membros estáticos de um tipo para que você possa chamá-los sem o prefixo de nome de tipo:

using static System.Math;

namespace MyApp.Utilities;

class CircleCalculator
{
    public static double CalculateArea(double radius) => PI * Pow(radius, 2);

    public static double CalculateCircumference(double radius) => 2 * PI * radius;
}

Os usos estáticos funcionam bem para classes de utilitário como Math e Console que você chama com frequência.

Aliases de tipo e namespace

Um using alias cria um nome abreviado para um tipo ou namespace. Os aliases são úteis para tipos genéricos longos, resolvendo conflitos de nomenclatura e melhorando a legibilidade:

using CustomerList = System.Collections.Generic.List<MyApp.Models.Customer>;

namespace MyApp.Services;

class CustomerService
{
    public CustomerList GetTopCustomers()
    {
        CustomerList customers = [new() { Name = "Alice" }, new() { Name = "Bob" }];
        return customers;
    }
}

A partir do C# 12, você pode alias qualquer tipo, incluindo tuplas e tipos de ponteiro:

using Point = (double X, double Y);

namespace MyApp.Geometry;

class Shape
{
    public static double Distance(Point a, Point b)
    {
        var dx = a.X - b.X;
        var dy = a.Y - b.Y;
        return Math.Sqrt(dx * dx + dy * dy);
    }
}

Para cenários mais avançados em que dois assemblies definem o mesmo nome de tipo totalmente qualificado, use extern alias para distinguir entre eles.

Conteúdo relacionado

  • Last updated on