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()
{
    // ...
}

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.

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

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 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.

Secciones relacionadas

Para obtener más información, vea:

• Crear atributos personalizados (C# y Visual Basic)

• 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)

• Atributos comunes (C# y Visual Basic)

Vea también

Referencia

Reflexión (C# y Visual Basic)

Conceptos

Guía de programación de C#

Extender metadatos mediante atributos

Otros recursos

Guía de programación en Visual Basic