Atributos (C#)Attributes (C#)

Los atributos proporcionan un método eficaz para asociar metadatos, o información declarativa, con código (ensamblados, tipos, métodos, propiedades, etc.).Attributes provide a powerful method of associating metadata, or declarative information, with code (assemblies, types, methods, properties, and so forth). Después de asociar un atributo con una entidad de programa, se puede consultar el atributo en tiempo de ejecución mediante la utilización de una técnica denominada reflexión.After an attribute is associated with a program entity, the attribute can be queried at run time by using a technique called reflection. Para obtener más información, vea Reflexión (C#).For more information, see Reflection (C#).

Los atributos tienen las propiedades siguientes:Attributes have the following properties:

  • Los atributos agregan metadatos al programa.Attributes add metadata to your program. Los metadatos son información sobre los tipos definidos en un programa.Metadata is information about the types defined in a program. Todos los ensamblados .NET contienen un conjunto de metadatos específico que describe los tipos y miembros de tipo definidos en el ensamblado.All .NET assemblies contain a specified set of metadata that describes the types and type members defined in the assembly. Puede agregar atributos personalizados para especificar cualquier información adicional que sea necesaria.You can add custom attributes to specify any additional information that is required. Para obtener más información, vea Crear atributos personalizados (C#).For more information, see, Creating Custom Attributes (C#).
  • Puede aplicar uno o más atributos a todos los ensamblados, módulos o elementos de programa más pequeños como clases y propiedades.You can apply one or more attributes to entire assemblies, modules, or smaller program elements such as classes and properties.
  • Los atributos pueden aceptar argumentos de la misma manera que los métodos y las propiedades.Attributes can accept arguments in the same way as methods and properties.
  • El programa puede examinar sus propios metadatos o los metadatos de otros programas mediante la reflexión.Your program can examine its own metadata or the metadata in other programs by using reflection. Para obtener más información, consulte Acceder a atributos mediante reflexión (C#).For more information, see Accessing Attributes by Using Reflection (C#).

Uso de atributosUsing attributes

Los atributos se pueden colocar en la mayoría de las declaraciones, aunque un determinado atributo podría restringir los tipos de declaraciones en que es válido.Attributes can be placed on most any declaration, though a specific attribute might restrict the types of declarations on which it is valid. En C#, para especificar un atributo se coloca su nombre entre corchetes ([]) por encima de la declaración de la entidad a la que se aplica.In C#, you specify an attribute by placing the name of the attribute enclosed in square brackets ([]) above the declaration of the entity to which it applies.

En este ejemplo, el atributo SerializableAttribute se usa para aplicar una característica específica a una clase:In this example, the SerializableAttribute attribute is used to apply a specific characteristic to a class:

[Serializable]
public class SampleClass
{
    // Objects of this type can be serialized.
}

Un método con el atributo DllImportAttribute se declara como en el siguiente ejemplo:A method with the attribute DllImportAttribute is declared like the following example:

[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();

En una declaración se puede colocar más de un atributo, como se muestra en el siguiente ejemplo:More than one attribute can be placed on a declaration as the following example shows:

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 más de una vez para una entidad determinada.Some attributes can be specified more than once for a given entity. Un ejemplo de este tipo de atributos multiuso es ConditionalAttribute:An example of such a multiuse attribute is ConditionalAttribute:

[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
    // ...
}

Nota

Por convención, todos los nombres de atributos terminan con la palabra "Attribute" para distinguirlos de otros elementos de las bibliotecas de .NET.By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET libraries. Sin embargo, no es necesario especificar el sufijo de atributo cuando utiliza atributos en el código.However, you do not need to specify the attribute suffix when using attributes in code. Por ejemplo, [DllImport] es equivalente a [DllImportAttribute], pero DllImportAttribute es el nombre real del atributo en la biblioteca de clases .NET Framework.For example, [DllImport] is equivalent to [DllImportAttribute], but DllImportAttribute is the attribute's actual name in the .NET Framework Class Library.

Parámetros de atributoAttribute parameters

Muchos atributos tienen parámetros, que pueden ser posicionales, sin nombre o con nombre.Many attributes have parameters, which can be positional, unnamed, or named. Los parámetros posicionales deben especificarse en un orden determinado y no se pueden omitir.Any positional parameters must be specified in a certain order and cannot be omitted. Los parámetros con nombre son opcionales y pueden especificarse en cualquier orden.Named parameters are optional and can be specified in any order. Los parámetros posicionales se especifican en primer lugar.Positional parameters are specified first. Por ejemplo, estos tres atributos son equivalentes:For example, these three attributes are equivalent:

[DllImport("user32.dll")]
[DllImport("user32.dll", SetLastError=false, ExactSpelling=false)]
[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]

El primer parámetro, el nombre del archivo DLL, es posicional y siempre va primero; los demás tienen un nombre.The first parameter, the DLL name, is positional and always comes first; the others are named. En este caso, ambos parámetros con nombre tienen el estado false de forma predeterminada, por lo que se pueden omitir.In this case, both named parameters default to false, so they can be omitted. Los parámetros posicionales corresponden a los parámetros del constructor de atributos.Positional parameters correspond to the parameters of the attribute constructor. Los parámetros con nombre u opcionales corresponden a propiedades o campos del atributo.Named or optional parameters correspond to either properties or fields of the attribute. Consulte la documentación del atributo individual para obtener información sobre los valores de parámetro predeterminados.Refer to the individual attribute's documentation for information on default parameter values.

Destinos de atributoAttribute targets

El destino de un atributo es la entidad a la que se aplica dicho atributo.The target of an attribute is the entity which the attribute applies to. Por ejemplo, puede aplicar un atributo a una clase, un método determinado o un ensamblado completo.For example, an attribute may apply to a class, a particular method, or an entire assembly. De forma predeterminada, el atributo se aplica al elemento que lo precede.By default, an attribute applies to the element that it precedes. Pero puede identificar explícitamente, por ejemplo, si se aplica un atributo a un método, a su parámetro o a su valor devuelto.But you can also explicitly identify, for example, whether an attribute is applied to a method, or to its parameter, or to its return value.

Para identificar un destino de atributo de forma explícita, use la sintaxis siguiente:To explicitly identify an attribute target, use the following syntax:

[target : attribute-list]

La lista de posibles valores target se muestra en la tabla siguiente.The list of possible target values is shown in the following table.

Valor del objetivoTarget value Se aplica aApplies to
assembly Ensamblado completoEntire assembly
module Módulo de ensamblado actualCurrent assembly module
field Campo de una clase o un structField in a class or a struct
event eventoEvent
method Método o descriptores de acceso de propiedad get y setMethod or get and set property accessors
param Parámetros de método o parámetros de descriptor de acceso de propiedad setMethod parameters or set property accessor parameters
property Propiedad.Property
return Valor devuelto de un método, indexador de propiedad o descriptor de acceso de propiedad getReturn value of a method, property indexer, or get property accessor
type Estructura, clase, interfaz, enumeración o delegadoStruct, class, interface, enum, or delegate

Debe especificar el valor de destino field para aplicar un atributo al campo de respaldo creado para una propiedad implementada automáticamente.You would specify the field target value to apply an attribute to the backing field created for an auto-implemented property.

En el ejemplo siguiente se muestra cómo aplicar atributos a ensamblados y módulos.The following example shows how to apply attributes to assemblies and modules. Para obtener más información, vea Atributos comunes (C#).For more information, see Common Attributes (C#).

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étodo y valores devueltos por métodos en C#.The following example shows how to apply attributes to methods, method parameters, and method return values in C#.

// default: applies to method
[ValidatedContract]
int Method1() { return 0; }

// applies to method
[method: ValidatedContract]
int Method2() { return 0; }

// applies to return value
[return: ValidatedContract]
int Method3() { return 0; }

Nota

Independientemente de los destinos en los que ValidatedContract se define para que sea válido, debe especificarse el destino return, incluso si ValidatedContract se ha definido para que se aplique solo a los valores devueltos.Regardless of the targets on which ValidatedContract is defined to be valid, the return target has to be specified, even if ValidatedContract were defined to apply only to return values. En otras palabras, el compilador no usará información de AttributeUsage para resolver destinos de atributo ambiguos.In other words, the compiler will not use AttributeUsage information to resolve ambiguous attribute targets. Para obtener más información, consulte AttributeUsage (C#).For more information, see AttributeUsage (C#).

Usos comunes de los atributosCommon uses for attributes

La lista siguiente incluye algunos de los usos comunes de atributos en el código:The following list includes a few of the common uses of attributes in code:

  • Marcar métodos con el atributo WebMethod en los servicios web para indicar que el método debe ser invocable a través del protocolo SOAP.Marking methods using the WebMethod attribute in Web services to indicate that the method should be callable over the SOAP protocol. Para obtener más información, vea WebMethodAttribute.For more information, see WebMethodAttribute.
  • Describir cómo serializar parámetros de método al interoperar con código nativo.Describing how to marshal method parameters when interoperating with native code. Para obtener más información, vea MarshalAsAttribute.For more information, see MarshalAsAttribute.
  • Describir las propiedades COM para clases, métodos e interfaces.Describing the COM properties for classes, methods, and interfaces.
  • Llamar al código no administrado mediante la clase DllImportAttribute.Calling unmanaged code using the DllImportAttribute class.
  • Describir los ensamblados en cuanto a título, versión, descripción o marca.Describing your assembly in terms of title, version, description, or trademark.
  • Describir qué miembros de una clase serializar para la persistencia.Describing which members of a class to serialize for persistence.
  • Describir cómo realizar asignaciones entre los miembros de clase y los nodos XML para la serialización XML.Describing how to map between class members and XML nodes for XML serialization.
  • Describir los requisitos de seguridad para los métodos.Describing the security requirements for methods.
  • Especificar las características utilizadas para reforzar la seguridad.Specifying characteristics used to enforce security.
  • Controlar optimizaciones mediante el compilador Just-In-Time (JIT) para que el código siga siendo fácil de depurar.Controlling optimizations by the just-in-time (JIT) compiler so the code remains easy to debug.
  • Obtener información sobre el llamador de un método.Obtaining information about the caller to a method.

Para obtener más información, consulte:For more information, see:

Vea tambiénSee also