Partilhar via

Espaços de nomes e utilização de diretivas

Sugestão

Novo no desenvolvimento de software? Começa primeiro pelos tutoriais para começar . Introduzem namespaces e using diretivas à medida que escreves os teus primeiros programas.

Experiente noutra língua? Os namespaces em C# funcionam de forma semelhante a pacotes em Java ou módulos em Python. Passa rapidamente até à sintaxe que precisas.

As declarações de namespace e diretivas using são características do idioma relacionadas. Uma declaração de namespace coloca os seus tipos numa estrutura organizada. Um espaço de nomes agrupa tipos relacionados e impede colisões de nomeação. Uma using diretiva permite que o seu programa consuma esses tipos pelos seus nomes simples. Não tens de soletrar o caminho completo do namespace em cada uso.

Já usou namespaces em todos os programas de C# que escreveu. Cada tipo .NET pertence a um namespace, e cada using diretiva no topo de um ficheiro faz referência a um. Por exemplo, Console e Math pertencem ao System espaço de nomes, pelo que os 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 destes espaços de nomes permite-lhe referir-se a todos os seus tipos pelos seus nomes simples. Escreves List<T> em vez de System.Collections.Generic.List<T> em todo o lado onde o usas.

Este artigo fornece mais contexto sobre como funcionam os namespaces e using as diretivas, e mostra exemplos de padrões que já encontraste nas bibliotecas .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.

É boa prática agrupar tipos relacionados ou semelhantes no mesmo espaço de nomes, e é isso que o .NET faz com os tipos que fornece. O System.Collections.Generic espaço de nomes contém tipos relacionados com coleções e o System.IO espaço de nomes contém tipos relacionados com ficheiros de leitura e escrita, diretórios e dados. O System namespace contém tipos fundamentais como Math, DateTime, e Console.

O exemplo seguinte mostra como os namespaces funcionam em conjunto com using diretivas num ficheiro 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 using diretiva significa que 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. O seu nome totalmente qualificado é MyApp.Services.Greeter.

Declarações de espaços de nomes

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

Os namespaces usam o . operador para expressar hierarquia, como System.Collections.Generic. Os nomes dos espaços de nomes devem ser nomes válidos de identificadores C#.

Namespaces definidos por arquivo

Use a sintaxe de escopo de ficheiro quando todos os tipos num ficheiro pertencem ao mesmo espaço de nomes. Adicione um ponto e vírgula após a declaração do namespace, e aplica-se a todo o ficheiro. Não precisas de chaves extras nem 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"})";
}

Os namespaces com escopo de ficheiros reduzem o aninhamento e tornam os ficheiros mais fáceis de ler. Só podes ter uma declaração de namespace com âmbito de ficheiro por ficheiro.

Sugestão

Use namespaces delimitados por ficheiro em código novo. A maioria dos templates e analisadores de código .NET recomenda este estilo.

Espaços de nomes restritos a blocos

Use sintaxe com escopo de blocos quando precisar de declarar mais do que um namespace no mesmo ficheiro. Este estilo adiciona um nível adicional de indentação.

Importante

É considerado má prática declarar mais do que um namespace no mesmo ficheiro. O cenário mais comum é usar namespaces com escopo ao nível do ficheiro.

O snippet seguinte é um exemplo de namespace com escopo de blocos :

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

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

Utilização de diretivas

Sem uma using diretiva, deve referir-se a cada tipo pelo seu nome totalmente qualificado, o caminho completo do espaço de nomes 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 no topo de um ficheiro importa um namespace para que possas usar os seus tipos pelos seus nomes simples:

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

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

Diretivas globais de uso

Se escreveres as mesmas using diretivas em cada ficheiro, as diretivas globais permitem-te declará-las uma vez para todo o teu projeto. Coloca-as em qualquer ficheiro. Muitas equipas criam um ficheiro dedicado GlobalUsings.cs :

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

Após declarar um uso global, cada ficheiro do projeto pode referir-se a tipos desse espaço de nomes usando nomes simples sem uma diretiva adicional using .

Utilizações implícitas

O SDK .NET gera automaticamente diretivas de uso global para os namespaces mais comuns, com base no tipo de projeto. Ative os usos implícitos definindo <ImplicitUsings>enable</ImplicitUsings> no ficheiro do 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 ativa ImplicitUsings quando cria um novo projeto usando dotnet new.

Para mais informações, veja Implícito usando diretivas.

Estática usando diretivas

Uma diretiva importa os membros estáticos de um tipo para que possa chamá-los sem o prefixo static using do nome do 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;
}

Usos estáticos funcionam bem para classes utilitárias como Math e Console que chamas frequentemente.

Aliases de tipos e namespaces

Um using alias cria um nome abreviado para um tipo ou namespace. Os pseudónimos são úteis para tipos genéricos longos, resolução de conflitos de nomes e melhoria da 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 de C# 12, podes usar qualquer tipo de alias, incluindo tuplas e tipos de ponteiros:

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 onde dois assemblies definem o mesmo nome de tipo totalmente qualificado, use alias externo para desambiguar entre eles.

Conteúdo relacionado

  • Last updated on