La directiva using

La directiva using permite usar tipos definidos en un espacio de nombres sin especificar el espacio de nombres completo de ese tipo. En su forma básica, la directiva using importa todos los tipos de un único espacio de nombres, como se muestra en el ejemplo siguiente:

using System.Text;

Puede aplicar dos modificadores a una directiva using:

• El modificador global tiene el mismo efecto que agregar la misma directiva using a todos los archivos de código fuente del proyecto. Este modificador se presentó en C# 10.
• El modificador static importa los miembros static y los tipos anidados de un solo tipo en lugar de importar todos los tipos de un espacio de nombres.

Puede combinar ambos modificadores para importar los miembros estáticos de un tipo a todos los archivos de origen del proyecto.

También puede crear un alias para un espacio de nombres o un tipo con una directiva de alias using.

using Project = PC.MyCompany.Project;

Puede usar el modificador global en una directiva de alias using.

El ámbito de una directiva using sin el modificador global es el archivo en el que aparece.

La global using directiva debe aparecer antes de todas las declaraciones de espacio de nombres y tipo. Todas las directivas using globales deben aparecer en un archivo de origen antes de cualquier directiva no global using .

Pueden aparecer otras using directivas:

• Al principio de un archivo de código fuente, antes de las declaraciones de espacio de nombres o de tipo.
• En cualquier espacio de nombres con ámbito bloqueado, pero antes de cualquier espacio de nombres o tipos declarados en ese espacio de nombres.

De lo contrario, se genera un error del compilador.

Cree una directiva using para usar los tipos de un espacio de nombres sin tener que especificarlo. Una directiva using no proporciona acceso a los espacios de nombres que están anidados en el espacio de nombres especificado. Los espacios de nombres se dividen en dos categorías: definidos por el sistema y definidos por el usuario. Los espacios de nombres definidos por el usuario son espacios de nombres definidos en el código. Para obtener una lista de los espacios de nombres definidos por el sistema, vea Explorador de API de .NET.

Modificador global

Agregar el modificador global a una directiva using hará que using se aplique a todos los archivos de la compilación (normalmente un proyecto). La directiva global using se agregó en C# 10. La sintaxis es:

global using <fully-qualified-namespace>;

Donde el espacio de nombres completo es el nombre completo del espacio de nombres cuyos tipos se pueden hacer referencia sin especificar el espacio de nombres.

Una directiva global using puede aparecer al principio de cualquier archivo de código fuente. Todas las directivas global using de un solo archivo deben aparecer antes de:

• Todas las directivas using sin el modificador global.
• Todas las declaraciones de espacio de nombres y de tipo del archivo.

Puede agregar global using directivas a cualquier archivo de origen. Normalmente, quiere mantenerlos en una sola ubicación. El orden de las directivas global using no importa, ya sea en un solo archivo o entre archivos.

El global modificador se puede combinar con el static modificador . El global modificador se puede aplicar a una directiva using alias. En ambos casos, el ámbito de la directiva son todos los archivos de la compilación actual. En el ejemplo siguiente se habilita el uso de todos los métodos declarados en System.Math en todos los archivos del proyecto:

global using static System.Math;

También puede incluir globalmente un espacio de nombres agregando un elemento <Using> al archivo del proyecto, por ejemplo, <Using Include="My.Awesome.Namespace" />. Para más información, consulte el elemento <Using>.

Los analizadores emiten diagnósticos si duplica global las directivas using en ubicaciones diferentes. Estos mismos analizadores también le informan si agrega una using directiva para un espacio de nombres o un tipo que ya hace referencia a una global directiva using. Es posible que le resulte más fácil administrar global los usos al mantenerlos juntos en un archivo del proyecto.

Modificador static

La directiva using static designa un tipo a cuyos miembros estáticos y tipos anidados se puede acceder sin especificar un nombre de tipo. La sintaxis es:

using static <fully-qualified-type-name>;

<fully-qualified-type-name> es el nombre del tipo a cuyos miembros estáticos y tipos anidados se puede hacer referencia sin especificar un nombre de tipo. Si no proporciona un nombre de tipo completo (el nombre del espacio de nombres completo junto con el nombre del tipo), C# genera el error del compilador CS0246: "El nombre del tipo o del espacio de nombres "tipo/espacio de nombres" no se encontró (¿falta una directiva using o una referencia de ensamblado?)".

La directiva using static se aplica a cualquier tipo que tenga miembros estáticos (o tipos anidados), aunque también tenga miembros de instancia. Pero los miembros de instancia solo pueden invocarse a través de la instancia del tipo.

Puede acceder a los miembros estáticos de un tipo sin tener que calificar el acceso con el nombre del tipo:

using static System.Console;
using static System.Math;
class Program
{
    static void Main()
    {
        WriteLine(Sqrt(3*3 + 4*4));
    }
}

Normalmente, cuando se llama a un miembro estático, se especifica el nombre de tipo junto con el nombre de miembro. Especificar varias veces el mismo nombre de tipo para invocar los miembros del tipo puede traducirse en código detallado y poco claro. Por ejemplo, en la definición siguiente de una clase Circle se hace referencia a numerosos miembros de la clase Math.

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

Al eliminar la necesidad de hacer referencia explícitamente a la clase Math cada vez que se hace referencia a un miembro, la directiva using static genera un código más limpio:

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 solo los miembros estáticos accesibles y los tipos anidados declarados en el tipo especificado. Los miembros heredados no se importan. Puede realizar la importación desde cualquier tipo con nombre con una directiva using static, como los módulos de Visual Basic. Las funciones de nivel superior F# pueden importarse si aparecen en los metadatos como miembros estáticos de un tipo con nombre cuyo nombre es un identificador de C# válido.

using static habilita los métodos de extensión declarados en el tipo especificado estén para la búsqueda de métodos de extensión. Sin embargo, los nombres de los métodos de extensión no se importan en el ámbito de referencia sin calificar del código.

Los métodos con el mismo nombre que se importen desde tipos distintos con distintas directivas using static en la misma unidad de compilación o espacio de nombres forman un grupo de métodos. La resolución de sobrecarga dentro de estos grupos de método sigue reglas normales de C#.

En el ejemplo siguiente se usa la directiva using static para que los miembros estáticos de las clases Console, Math y String estén disponibles sin tener que especificar su nombre de tipo.

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

En el ejemplo, la using static directiva también se podría aplicar al Double tipo . Agregar esa directiva habría permitido llamar al método TryParse(String, Double) sin especificar un nombre de tipo. Sin embargo, el uso de TryParse sin un nombre de tipo crea un código menos legible, ya que es necesario comprobar las directivas using static para determinar el método TryParse del tipo numérico al que se llama.

using static también se aplica a los tipos enum. Al agregar using static con la enumeración, el tipo ya no es necesario para usar los miembros de la enumeración.

using static Color;

enum Color
{
    Red,
    Green,
    Blue
}

class Program
{
    public static void Main()
    {
        Color color = Green;
    }
}

Alias using

Cree una directiva de alias using para facilitar la calificación de un identificador como espacio de nombres o tipo. En cualquier directiva using, hay que usar el espacio de nombres o el tipo con cualificación completa, independientemente de las directivas using que los precedan. No se puede usar ningún alias using en la declaración de una directiva using. Por ejemplo, en el ejemplo siguiente se genera un error del compilador:

using s = System.Text;
using s.RegularExpressions; // Generates a compiler error.

En el ejemplo siguiente se muestra cómo definir y usar un alias using para un espacio de nombres:

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 { }
        }
    }
}

Una directiva de alias using no puede tener un tipo genérico abierto en el lado derecho. Por ejemplo, no puede crear un alias using para un elemento List<T>, pero puede crear uno para un elemento List<int>.

En el ejemplo siguiente se muestra cómo definir una directiva using y un alias using para una clase:

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 de C# 12, puede crear alias para los tipos que estaban restringidos anteriormente, incluidos los tipos de tupla, los tipos de puntero y otros tipos no seguros. Para obtener más información sobre las reglas actualizadas, consulte la especificación de características.

Miembro de alias calificado

El calificador de alias de espacio de nombres proporciona :: acceso explícito al espacio de nombres global u otros mediante alias potencialmente ocultos por otras entidades.

global:: garantiza que la búsqueda del espacio de nombres para el espacio de nombres que sigue al :: token es relativa al espacio de nombres global. De lo contrario, el token debe resolverse en un alias mediante y el token siguiente :: debe resolverse en un tipo de ese espacio de nombres con alias. En el ejemplo siguiente se muestran ambos formularios:

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

Especificación del lenguaje C#

Para obtener más información, vea la sección Directivas using de la Especificación del lenguaje C#. La especificación del lenguaje es la fuente definitiva de la sintaxis y el uso de C#.

Para obtener más información sobre el modificador global using, consulte la especificación de la característica global using: C# 10.

Consulte también

• Palabras clave de C#
• Espacios de nombres
• Regla de estilo IDE0005: Eliminación de directivas "using" innecesarias
• Regla de estilo IDE0065: Colocación de directivas "using"
• Instrucción using