A using diretiva
A using diretiva permite que você use tipos definidos em um namespace sem especificar o namespace totalmente qualificado desse tipo. Em sua forma básica, a using diretiva importa todos os tipos de um único namespace, conforme mostrado no exemplo a seguir:
using System.Text;
Você pode aplicar dois modificadores a uma using diretiva:
- O
globalmodificador tem o mesmo efeito que adicionar a mesmausingdiretiva a cada arquivo de origem em seu projeto. - O
staticmodificador importa os membros e osstatictipos aninhados de um único tipo em vez de importar todos os tipos em um namespace.
Você pode combinar ambos os modificadores para importar os membros estáticos de um tipo para todos os arquivos de origem em seu projeto.
Você também pode criar um alias para um namespace ou um tipo com uma diretiva using alias.
using Project = PC.MyCompany.Project;
Você pode usar o global modificador em uma diretiva using alias.
Nota
A using palavra-chave também é usada para criar using instruções, que ajudam a garantir que IDisposable objetos como arquivos e fontes sejam manipulados corretamente. Para obter mais informações sobre a instrução, consulteusinga using.
O âmbito de aplicação de uma using diretiva sem o global modificador é o ficheiro em que aparece.
A global using diretiva deve aparecer antes de todas as declarações de namespace e tipo. Todas as diretivas de uso global devem aparecer em um arquivo de origem antes de quaisquer diretivas não globais using .
Podem surgir outras using diretivas:
- No início de um arquivo de código-fonte, antes de qualquer namespace ou declarações de tipo.
- Em qualquer namespace com escopo bloqueado, mas antes de quaisquer namespaces ou tipos declarados nesse namespace.
Caso contrário, um erro de compilador é gerado.
Crie uma using diretiva para usar os tipos em um namespace sem precisar especificar o namespace. Uma using diretiva não lhe dá acesso a nenhum namespace aninhado no namespace especificado. Os namespaces vêm em duas categorias: definidos pelo usuário e definidos pelo sistema. Namespaces definidos pelo usuário são namespaces definidos em seu código. Para obter uma lista dos namespaces definidos pelo sistema, consulte .NET API Browser.
O global modificador
Adicionar o modificador global a uma diretiva using significa que o uso é aplicado a todos os arquivos na compilação (normalmente um projeto):
global using <fully-qualified-namespace>;
Onde full-qualified-namespace é o nome totalmente qualificado do namespace cujos tipos podem ser referenciados sem especificar o namespace.
Uma diretiva global using pode aparecer no início de qualquer arquivo de código-fonte. Todas as global using diretivas em um único arquivo devem aparecer antes:
- Todas
usingas diretivas sem oglobalmodificador. - Todas as declarações de namespace e tipo no arquivo.
Você pode adicionar global using diretivas a qualquer arquivo de origem. Normalmente, você deseja mantê-los em um único local. A ordem das global using diretivas não importa, nem em um único arquivo, nem entre arquivos.
O global modificador pode ser combinado com o static modificador. O global modificador pode ser aplicado a uma diretiva using alias. Em ambos os casos, o âmbito de aplicação da diretiva são todos os ficheiros da compilação atual. O exemplo a seguir permite usar todos os métodos declarados no System.Math em todos os arquivos em seu projeto:
global using static System.Math;
Você também pode incluir globalmente um namespace adicionando um <Using> item ao seu arquivo de projeto, por exemplo, <Using Include="My.Awesome.Namespace" />. Para obter mais informações, consulte <Using> o item.
Os analisadores emitem diagnósticos se você duplicar global o uso de diretivas em locais diferentes. Esses mesmos analisadores também informam se você adicionar uma using diretiva para um namespace ou tipo que uma global diretiva de uso já faz referência. Você pode achar mais fácil gerenciar seus global usos mantendo-os juntos em um arquivo no projeto.
Importante
Os modelos C# para .NET 6 usam instruções de nível superior. Seu aplicativo pode não corresponder ao código neste artigo, se você já tiver atualizado para o .NET 6. Para obter mais informações, consulte o artigo sobre Novos modelos C# geram instruções de nível superior
O SDK do .NET 6 também adiciona um conjunto de diretivas implícitasglobal using para projetos que usam os seguintes SDKs:
- Microsoft.NET.Sdk
- Microsoft.NET.Sdk.Web
- Microsoft.NET.Sdk.Trabalhador
Essas diretivas implícitas global using incluem os namespaces mais comuns para o tipo de projeto.
Para obter mais informações, consulte o artigo sobre Uso implícito de diretivas
O static modificador
A using static diretiva nomeia um tipo cujos membros estáticos e tipos aninhados você pode acessar sem especificar um nome de tipo. Sua sintaxe é:
using static <fully-qualified-type-name>;
O <fully-qualified-type-name> é o nome do tipo cujos membros estáticos e tipos aninhados podem ser referenciados sem especificar um nome de tipo. Se você não fornecer um nome de tipo totalmente qualificado (o nome completo do namespace junto com o nome do tipo), o C# gerará o erro do compilador CS0246: "O nome do tipo ou namespace 'type/namespace' não pôde ser encontrado (você está faltando uma diretiva de uso ou uma referência de assembly?)".
A using static diretiva aplica-se a qualquer tipo que tenha membros estáticos (ou tipos aninhados), mesmo que também tenha membros de instância. No entanto, os membros da instância só podem ser invocados por meio da instância de tipo.
Você pode acessar membros estáticos de um tipo sem ter que qualificar o acesso com o nome do tipo:
using static System.Console;
using static System.Math;
class Program
{
static void Main()
{
WriteLine(Sqrt(3*3 + 4*4));
}
}
Normalmente, quando você chama um membro estático, você fornece o nome do tipo junto com o nome do membro. Digitar repetidamente o mesmo nome de tipo para invocar membros do tipo pode resultar em código detalhado e obscuro. Por exemplo, a seguinte definição de uma Circle classe faz referência a muitos membros da Math classe.
using System;
public class Circle
{
public Circle(double radius)
{
Radius = radius;
}
public double Radius { get; set; }
public double Diameter
{
get { return 2 * Radius; }
}
public double Circumference
{
get { return 2 * Radius * Math.PI; }
}
public double Area
{
get { return Math.PI * Math.Pow(Radius, 2); }
}
}
Ao eliminar a necessidade de fazer referência explícita à Math classe cada vez que um membro é referenciado, a using static diretiva produz um código mais limpo:
using System;
using static System.Math;
public class Circle
{
public Circle(double radius)
{
Radius = radius;
}
public double Radius { get; set; }
public double Diameter
{
get { return 2 * Radius; }
}
public double Circumference
{
get { return 2 * Radius * PI; }
}
public double Area
{
get { return PI * Pow(Radius, 2); }
}
}
using static Importa apenas membros estáticos acessíveis e tipos aninhados declarados no tipo especificado. Os membros herdados não são importados. Você pode importar de qualquer tipo nomeado com uma using static diretiva, incluindo módulos do Visual Basic. Se as funções de nível superior F# aparecerem nos metadados como membros estáticos de um tipo nomeado cujo nome é um identificador C# válido, as funções F# podem ser importadas.
using static Disponibiliza métodos de extensão declarados no tipo especificado para pesquisa de método de extensão. No entanto, os nomes dos métodos de extensão não são importados para o escopo para referência não qualificada no código.
Métodos com o mesmo nome importados de tipos diferentes por diretivas diferentes using static na mesma unidade de compilação ou namespace formam um grupo de métodos. A resolução de sobrecarga dentro desses grupos de métodos segue regras normais de C#.
O exemplo a seguir usa a using static diretiva para disponibilizar os membros estáticos das classes , Consolee Math sem precisar especificar seu nome de Stringtipo.
using System;
using static System.Console;
using static System.Math;
using static System.String;
class Program
{
static void Main()
{
Write("Enter a circle's radius: ");
var input = ReadLine();
if (!IsNullOrEmpty(input) && double.TryParse(input, out var radius)) {
var c = new Circle(radius);
string s = "\nInformation about the circle:\n";
s = s + Format(" Radius: {0:N2}\n", c.Radius);
s = s + Format(" Diameter: {0:N2}\n", c.Diameter);
s = s + Format(" Circumference: {0:N2}\n", c.Circumference);
s = s + Format(" Area: {0:N2}\n", c.Area);
WriteLine(s);
}
else {
WriteLine("Invalid input...");
}
}
}
public class Circle
{
public Circle(double radius)
{
Radius = radius;
}
public double Radius { get; set; }
public double Diameter
{
get { return 2 * Radius; }
}
public double Circumference
{
get { return 2 * Radius * PI; }
}
public double Area
{
get { return PI * Pow(Radius, 2); }
}
}
// The example displays the following output:
// Enter a circle's radius: 12.45
//
// Information about the circle:
// Radius: 12.45
// Diameter: 24.90
// Circumference: 78.23
// Area: 486.95
No exemplo, a using static diretiva também poderia ser aplicada ao Double tipo. O aditamento desta diretiva permitiria chamar o método sem especificar um nome de TryParse(String, Double) tipo. No entanto, usar TryParse sem um nome de tipo cria um código menos legível, uma vez que se torna necessário verificar as using static diretivas para determinar qual método do TryParse tipo numérico é chamado.
using static também se aplica aos enum tipos. Ao adicionar using static com o enum, o tipo não é mais necessário para usar os membros enum.
using static Color;
enum Color
{
Red,
Green,
Blue
}
class Program
{
public static void Main()
{
Color color = Green;
}
}
O using pseudónimo
Crie uma using diretiva de alias para facilitar a qualificação de um identificador para um namespace ou tipo. Em qualquer using diretiva, o namespace ou tipo totalmente qualificado deve ser usado independentemente das using diretivas que vêm antes dele. Nenhum using pseudónimo pode ser utilizado na declaração de uma using diretiva. Por exemplo, o exemplo a seguir gera um erro de compilador:
using s = System.Text;
using s.RegularExpressions; // Generates a compiler error.
O exemplo a seguir mostra como definir e usar um using alias para um namespace:
namespace PC
{
// Define an alias for the nested namespace.
using Project = PC.MyCompany.Project;
class A
{
void M()
{
// Use the alias
var mc = new Project.MyClass();
}
}
namespace MyCompany
{
namespace Project
{
public class MyClass { }
}
}
}
Uma diretiva de alias de uso não pode ter um tipo genérico aberto no lado direito. Por exemplo, você não pode criar um alias de uso para um List<T>, mas pode criar um para um List<int>.
O exemplo a seguir mostra como definir uma using diretiva e um using alias para uma classe:
using System;
// Using alias directive for a class.
using AliasToMyClass = NameSpace1.MyClass;
// Using alias directive for a generic class.
using UsingAlias = NameSpace2.MyClass<int>;
namespace NameSpace1
{
public class MyClass
{
public override string ToString()
{
return "You are in NameSpace1.MyClass.";
}
}
}
namespace NameSpace2
{
class MyClass<T>
{
public override string ToString()
{
return "You are in NameSpace2.MyClass.";
}
}
}
namespace NameSpace3
{
class MainClass
{
static void Main()
{
var instance1 = new AliasToMyClass();
Console.WriteLine(instance1);
var instance2 = new UsingAlias();
Console.WriteLine(instance2);
}
}
}
// Output:
// You are in NameSpace1.MyClass.
// You are in NameSpace2.MyClass.
A partir do C# 12, você pode criar aliases para tipos que eram restritos anteriormente, incluindo tipos de tupla, tipos de ponteiro e outros tipos não seguros. Para obter mais informações sobre as regras atualizadas, consulte as especificações do recurso.
Membro qualificado do alias
O qualificador :: de alias de namespace fornece acesso explícito ao namespace global ou outro usando aliases potencialmente ocultos por outras entidades.
O global:: garante que a pesquisa de namespace para o namespace após o :: token seja relativa ao namespace global. Caso contrário, o token deve ser resolvido para um alias de uso e o token que segue o :: deve ser resolvido para um tipo nesse namespace com alias. O exemplo a seguir mostra ambas as formas:
using S = System.Net.Sockets;
class A
{
public static int x;
}
class C
{
public void F(int A, object S)
{
// Use global::A.x instead of A.x
global::A.x += A;
// Using ::, S must resolve to a namespace alias:
S::Socket s = S as S::Socket;
// In this form, if S were a class, it would be a compile-time error:
S.Socket s1 = S as S.Socket;
}
}
Especificação da linguagem C#
Para obter mais informações, consulte Usando diretivas na especificação de linguagem C#. A especificação da linguagem é a fonte definitiva para a sintaxe e o uso do C#.
Para obter mais informações sobre o global usando modificador, consulte o global usings feature specification.
