Atributos (C# y Visual Basic)
Los atributos constituyen un medio apropiado para asociar metadatos o información declarativa con código (ensamblados, tipos, métodos, propiedades, etc.). Después de asociar un atributo a una entidad del programa, éste se puede consultar en tiempo de ejecución mediante una técnica denominada reflexión. Para obtener más información, vea Reflexión (C# y Visual Basic).
Los atributos tienen las propiedades siguientes:
Los atributos agregan metadatos al programa. Los metadatos son información sobre los tipos definidos en un programa. Todos los ensamblados .NET contienen un conjunto de metadatos especificado que describe los tipos y los miembros de tipo definidos en el ensamblado. Puede agregar atributos personalizados para especificar toda información adicional necesaria. Para obtener más información, vea Crear atributos personalizados (C# y Visual Basic).
Se puede aplicar uno o más atributos a todos los ensamblados, módulos o elementos de programa más pequeños, como las clases y las propiedades.
Los atributos pueden aceptar argumentos del mismo modo que los métodos y las propiedades.
El programa puede examinar sus propios metadatos o los metadatos de otros programas mediante la reflexión. Para obtener más información, vea Obtener acceso a los atributos mediante la reflexión (C# y Visual Basic).
Usar atributos
Los atributos se pueden colocar en la mayoría de las declaraciones, aunque un determinado atributo podría restringir los tipos de declaraciones en las que es válido. En C#, un atributo se especifica colocando el nombre del atributo, encerrado entre corchetes ([]), encima de la declaración de la entidad a la que se aplica. En Visual Basic, el atributo se encierra entre corchetes angulares (< >). Debe aparecer inmediatamente delante del elemento al que se aplica, en la misma línea.
En este ejemplo, el atributo SerializableAttribute se utiliza para aplicar una característica específica a una clase:
<System.Serializable()> Public Class SampleClass
' Objects of this type can be serialized.
End Class
[System.Serializable]
public class SampleClass
{
// Objects of this type can be serialized.
}
Un método con el atributo DllImportAttribute se declara así:
Imports System.Runtime.InteropServices
...
<System.Runtime.InteropServices.DllImport("user32.dll")>
Sub SampleMethod()
End Sub
using System.Runtime.InteropServices;
...
[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();
Se puede colocar más de un atributo en una declaración:
Imports System.Runtime.InteropServices
...
Sub MethodA(<[In](), Out()> ByVal x As Double)
End Sub
Sub MethodB(<Out(), [In]()> ByVal x As Double)
End Sub
using System.Runtime.InteropServices;
...
void MethodA([In][Out] ref double x) { }
void MethodB([Out][In] ref double x) { }
void MethodC([In, Out] ref double x) { }
Algunos atributos se pueden especificar varias veces para una entidad dada. Un ejemplo de este tipo de atributos multiuso es ConditionalAttribute:
<Conditional("DEBUG"), Conditional("TEST1")>
Sub TraceMethod()
End Sub
[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
// ...
}
Nota
Por convención, todos los nombres de atributo finalizan con la palabra "Attribute" para distinguirlos de otros elementos de .NET Framework.No obstante, no tiene que especificar el sufijo de atributo cuando utiliza atributos en el código.Por ejemplo, [DllImport] equivale a [DllImportAttribute], pero DllImportAttribute es el nombre real del atributo en .NET Framework.
Parámetros de atributo
Muchos atributos tienen parámetros, que pueden ser posicionales, sin nombre, o con nombre. Los parámetros posicionales se deben especificar en un determinado orden y no se pueden omitir; los parámetros con nombre son opcionales y se pueden especificar en cualquier orden. Los parámetros posicionales se especifican en primer lugar. Por ejemplo, estos tres atributos son equivalentes:
[DllImport("user32.dll")]
[DllImport("user32.dll", SetLastError=false, ExactSpelling=false)]
[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]
<DllImport("user32.dll")>
<DllImport("user32.dll", SetLastError:=False, ExactSpelling:=False)>
<DllImport("user32.dll", ExactSpelling:=False, SetLastError:=False)>
El primer parámetro, el nombre de la DLL, es posicional y va siempre en primer lugar; los otros dos son parámetros con nombre. En este caso, ambos parámetros con nombre se establecen como falso de forma predeterminada, por lo que se pueden omitir. Consulte la documentación del atributo individual para obtener información sobre los valores de parámetro predeterminados.
Destinos de atributo
El destino de un atributo es la entidad a la que se aplica el atributo. Por ejemplo, un atributo se puede aplicar a una clase, un método determinado o un ensamblado completo. De forma predeterminada, un atributo se aplica al elemento que precede. Pero también se puede identificar explícitamente; por ejemplo, si un atributo se aplica a un método, a su parámetro o a su valor devuelto.
Para identificar un destino de atributo explícitamente, utilice la sintaxis siguiente:
[target : attribute-list]
<target : attribute-list>
La lista de posibles valores de target se muestra en la tabla siguiente.
C# |
Visual Basic |
Se aplica a |
|---|---|---|
assembly |
Assembly |
Ensamblado completo |
module |
Module |
Módulo de ensamblado actual (que es diferente de un módulo de Visual Basic) |
field |
No compatible |
Campo de una clase o struct |
event |
No compatible |
Evento |
method |
No compatible |
Método o descriptores de acceso de propiedad get y set |
param |
No compatible |
Parámetros de método o parámetros de descriptor de acceso de propiedad set |
property |
No compatible |
Propiedad |
return |
No compatible |
Valor devuelto de un método, indizador de propiedad o descriptor de acceso de propiedad get |
type |
No compatible |
Struct, clase, interfaz, enumeración o delegado |
En el ejemplo siguiente se muestra cómo aplicar atributos a ensamblados y módulos. Para obtener más información, vea Atributos comunes (C# y Visual Basic).
Imports System.Reflection
<Assembly: AssemblyTitleAttribute("Production assembly 4"),
Module: CLSCompliant(True)>
using System;
using System.Reflection;
[assembly: AssemblyTitleAttribute("Production assembly 4")]
[module: CLSCompliant(true)]
En el ejemplo siguiente se muestra cómo aplicar atributos a métodos, parámetros de métodos y valores devueltos de métodos en C#.
// default: applies to method
[SomeAttr]
int Method1() { return 0; }
// applies to method
[method: SomeAttr]
int Method2() { return 0; }
// applies to return value
[return: SomeAttr]
int Method3() { return 0; }
Nota
Con independencia de los destinos en que SomeAttr se define como válido, se ha de especificar el destino return, aunque SomeAttr se haya definido para aplicarse sólo a valores devueltos.Dicho de otra forma, el compilador no utilizará información de AttributeUsage para resolver destinos de atributo ambiguos.Para obtener más información, vea AttributeUsage (C# y Visual Basic).
Usos comunes de los atributos
La lista siguiente incluye algunos usos comunes de los atributos en el código:
Marcar métodos utilizando el atributo WebMethod en los servicios Web para indicar que se podrán invocar con el protocolo SOAP. Para obtener más información, vea WebMethodAttribute.
Describir cómo calcular las referencias de parámetros a método cuando se interopera con código nativo. Para obtener más información, vea MarshalAsAttribute.
Describir las propiedades COM para clases, métodos e interfaces.
Llamar a código no administrado mediante la clase DllImportAttribute.
Describir los ensamblados en cuanto a título, versión, descripción o marca.
Describir qué miembros de una clase hay que serializar para la persistencia.
Describir cómo realizar asignaciones entre miembros de clases y nodos XML para la serialización de XML.
Describir los requisitos de seguridad para métodos.
Especificar las características utilizadas para reforzar la seguridad.
Controlar optimizaciones mediante el compilador just-in-time (JIT) para que el código se conserve sencillo para depurar.
Obtener información sobre el llamador a un método.
Secciones relacionadas
Para obtener más información, vea:
Obtener acceso a los atributos mediante la reflexión (C# y Visual Basic)
Cómo: Crear una unión en C/C++ mediante atributos (C# y Visual Basic)