Atributos comunes (C#)Common Attributes (C#)

En este tema se describen los atributos que más se usan en los programas de C#.This topic describes the attributes that are most commonly used in C# programs.

Atributos globalesGlobal Attributes

La mayoría de los atributos se aplican a elementos específicos del lenguaje, como las clases o los métodos, aunque algunos atributos son globales (se aplican a todo un ensamblado o módulo).Most attributes are applied to specific language elements such as classes or methods; however, some attributes are global—they apply to an entire assembly or module. Por ejemplo, el atributo AssemblyVersionAttribute se puede usar para insertar información de versión en un ensamblado, como en este ejemplo:For example, the AssemblyVersionAttribute attribute can be used to embed version information into an assembly, like this:

[assembly: AssemblyVersion("1.0.0.0")]  

Los atributos globales aparecen en el código fuente después de cualquier directiva using de nivel superior y antes de cualquier declaración de espacio de nombres, módulo o tipo.Global attributes appear in the source code after any top-level using directives and before any type, module, or namespace declarations. Los atributos globales pueden aparecer en varios archivos de código fuente, pero estos archivos se deben compilar en un solo paso de compilación.Global attributes can appear in multiple source files, but the files must be compiled in a single compilation pass. En los proyectos de C#, los atributos globales se colocan en el archivo AssemblyInfo.cs.In C# projects, global attributes are put in the AssemblyInfo.cs file.

Los atributos de ensamblado son valores que proporcionan información sobre un ensamblado.Assembly attributes are values that provide information about an assembly. Se dividen en las siguientes categorías:They fall into the following categories:

  • Atributos de identidad del ensambladoAssembly identity attributes

  • Atributos informativosInformational attributes

  • Atributos de manifiesto del ensambladoAssembly manifest attributes

Atributos de identidad del ensambladoAssembly Identity Attributes

Tres atributos, con un nombre seguro (si procede), determinan la identidad de un ensamblado: nombre, versión y referencia cultural.Three attributes (with a strong name, if applicable) determine the identity of an assembly: name, version, and culture. Estos atributos forman el nombre completo del ensamblado y son necesarios cuando se hace referencia a este en el código.These attributes form the full name of the assembly and are required when you reference it in code. Puede establecer la versión y la referencia cultural de un ensamblado mediante atributos,You can set an assembly's version and culture using attributes. pero el valor de nombre lo establece el compilador, el IDE de Visual Studio en el cuadro de diálogo de información de ensamblado o la herramienta Assembly Linker (Al.exe) cuando se crea el ensamblado, a partir del archivo que contiene el manifiesto del ensamblado.However, the name value is set by the compiler, the Visual Studio IDE in the Assembly Information Dialog Box, or the Assembly Linker (Al.exe) when the assembly is created, based on the file that contains the assembly manifest. El atributo AssemblyFlagsAttribute especifica si pueden coexistir varias copias del ensamblado.The AssemblyFlagsAttribute attribute specifies whether multiple copies of the assembly can coexist.

En la siguiente tabla se muestran los atributos de identidad.The following table shows the identity attributes.

AtributoAttribute PropósitoPurpose
AssemblyName Describe completamente la identidad de un ensamblado.Fully describes the identity of an assembly.
AssemblyVersionAttribute Especifica la versión de un ensamblado.Specifies the version of an assembly.
AssemblyCultureAttribute Especifica la cultura que admite el ensamblado.Specifies which culture the assembly supports.
AssemblyFlagsAttribute Especifica si un ensamblado admite la ejecución en paralelo en el mismo equipo, en el mismo proceso o en el mismo dominio de aplicación.Specifies whether an assembly supports side-by-side execution on the same computer, in the same process, or in the same application domain.

Atributos informativosInformational Attributes

Puede utilizar atributos informativos para proporcionar información adicional de la compañía o de producto para un ensamblado.You can use informational attributes to provide additional company or product information for an assembly. En la tabla siguiente se muestran los atributos informativos definidos en el espacio de nombres System.Reflection.The following table shows the informational attributes defined in the System.Reflection namespace.

AtributoAttribute PropósitoPurpose
AssemblyProductAttribute Define un atributo personalizado que especifica un nombre de producto para un manifiesto del ensamblado.Defines a custom attribute that specifies a product name for an assembly manifest.
AssemblyTrademarkAttribute Define un atributo personalizado que especifica una marca comercial para un manifiesto del ensamblado.Defines a custom attribute that specifies a trademark for an assembly manifest.
AssemblyInformationalVersionAttribute Define un atributo personalizado que especifica una versión informativa para un manifiesto del ensamblado.Defines a custom attribute that specifies an informational version for an assembly manifest.
AssemblyCompanyAttribute Define un atributo personalizado que especifica un nombre de compañía para un manifiesto del ensamblado.Defines a custom attribute that specifies a company name for an assembly manifest.
AssemblyCopyrightAttribute Define un atributo personalizado que especifica un copyright para un manifiesto del ensamblado.Defines a custom attribute that specifies a copyright for an assembly manifest.
AssemblyFileVersionAttribute Indica al compilador que use un número de versión específico para el recurso de versión de archivo Win32.Instructs the compiler to use a specific version number for the Win32 file version resource.
CLSCompliantAttribute Indica si el ensamblado es compatible con Common Language Specification (CLS).Indicates whether the assembly is compliant with the Common Language Specification (CLS).

Atributos de manifiesto del ensambladoAssembly Manifest Attributes

Puede usar los atributos de manifiesto del ensamblado para proporcionar información en el manifiesto del ensambladoYou can use assembly manifest attributes to provide information in the assembly manifest. (título, descripción, alias predeterminado y configuración).This includes title, description, default alias, and configuration. En la tabla siguiente se muestran los atributos de manifiesto del ensamblado definidos en el espacio de nombres System.Reflection.The following table shows the assembly manifest attributes defined in the System.Reflection namespace.

AtributoAttribute PropósitoPurpose
AssemblyTitleAttribute Define un atributo personalizado que especifica un título de ensamblado para un manifiesto del ensamblado.Defines a custom attribute that specifies an assembly title for an assembly manifest.
AssemblyDescriptionAttribute Define un atributo personalizado que especifica una descripción de ensamblado para un manifiesto del ensamblado.Defines a custom attribute that specifies an assembly description for an assembly manifest.
AssemblyConfigurationAttribute Define un atributo personalizado que especifica una configuración de ensamblado (por ejemplo, comercial o depuración) para un manifiesto del ensamblado.Defines a custom attribute that specifies an assembly configuration (such as retail or debug) for an assembly manifest.
AssemblyDefaultAliasAttribute Define un alias descriptivo predeterminado para un manifiesto del ensamblado.Defines a friendly default alias for an assembly manifest

Atributo ObsoleteObsolete Attribute

El atributo Obsolete marca una entidad del programa como una entidad cuyo uso ya no se recomienda.The Obsolete attribute marks a program entity as one that is no longer recommended for use. Cada uso de una entidad marcada como obsoleta generará posteriormente una advertencia o un error, en función de la configuración del atributo.Each use of an entity marked obsolete will subsequently generate a warning or an error, depending on how the attribute is configured. Por ejemplo:For example:

[System.Obsolete("use class B")]  
class A  
{  
    public void Method() { }  
}  
class B  
{  
    [System.Obsolete("use NewMethod", true)]  
    public void OldMethod() { }  
    public void NewMethod() { }  
}  

En este ejemplo, el atributo Obsolete se aplica a la clase A y al método B.OldMethod.In this example the Obsolete attribute is applied to class A and to method B.OldMethod. Dado que el segundo argumento del constructor de atributos aplicado a B.OldMethod está establecido en true, este método producirá un error del compilador, mientras que, si se usa la clase A, solo se generará una advertencia.Because the second argument of the attribute constructor applied to B.OldMethod is set to true, this method will cause a compiler error, whereas using class A will just produce a warning. En cambio, si se llama a B.NewMethod, no se generará ninguna advertencia o error.Calling B.NewMethod, however, produces no warning or error.

La cadena proporcionada como primer argumento al constructor de atributos se mostrará como parte de la advertencia o error.The string provided as the first argument to attribute constructor will be displayed as part of the warning or error. Por ejemplo, al usarla con las definiciones anteriores, el código siguiente genera dos advertencias y un error:For example, when you use it with the previous definitions, the following code generates two warnings and one error:

// Generates 2 warnings:  
// A a = new A();  
  
// Generate no errors or warnings:  
B b = new B();  
b.NewMethod();  
  
// Generates an error, terminating compilation:  
// b.OldMethod();  

Se generan dos advertencias para la clase A: una para la declaración de la referencia de clase y otra para el constructor de clases.Two warnings for class A are generated: one for the declaration of the class reference, and one for the class constructor.

El atributo Obsolete se puede usar sin argumentos, aunque se recomienda incluir una explicación de por qué el elemento está obsoleto y qué se debe usar en su lugar.The Obsolete attribute can be used without arguments, but including an explanation of why the item is obsolete and what to use instead is recommended.

El atributo Obsolete es un atributo de uso único y se puede aplicar a cualquier entidad que admita atributos.The Obsolete attribute is a single-use attribute and can be applied to any entity that allows attributes. Obsolete es un alias de ObsoleteAttribute.Obsolete is an alias for ObsoleteAttribute.

Atributo ConditionalConditional Attribute

El atributo Conditional hace que la ejecución de un método dependa de un identificador de preprocesamiento.The Conditional attribute makes the execution of a method dependent on a preprocessing identifier. El atributo Conditional es un alias de ConditionalAttribute y se puede aplicar a un método o a una clase de atributo.The Conditional attribute is an alias for ConditionalAttribute, and can be applied to a method or an attribute class.

En este ejemplo, Conditional se aplica a un método para habilitar o deshabilitar la visualización de información de diagnóstico específica del programa:In this example, Conditional is applied to a method to enable or disable the display of program-specific diagnostic information:

#define TRACE_ON  
using System;  
using System.Diagnostics;  
  
public class Trace  
{  
    [Conditional("TRACE_ON")]  
    public static void Msg(string msg)  
    {  
        Console.WriteLine(msg);  
    }  
}  
  
public class ProgramClass  
{  
    static void Main()  
    {  
        Trace.Msg("Now in Main...");  
        Console.WriteLine("Done.");  
    }  
}  

Si el identificador TRACE_ON no está definido, no se mostrará ningún resultado del seguimiento.If the TRACE_ON identifier is not defined, no trace output will be displayed.

El atributo Conditional se suele usar con el identificador DEBUG para habilitar las funciones de seguimiento y de registro para las compilaciones de depuración (pero no en las compilaciones de versión), como en este ejemplo:The Conditional attribute is often used with the DEBUG identifier to enable trace and logging features for debug builds but not in release builds, like this:

[Conditional("DEBUG")]  
static void DebugMethod()  
{  
}  

Al llamar a un método marcado como condicional, la presencia o ausencia del símbolo de preprocesamiento especificado determina si se incluye o se omite la llamada.When a method marked as conditional is called, the presence or absence of the specified preprocessing symbol determines whether the call is included or omitted. Si el símbolo está definido, se incluye la llamada; de lo contrario, se omite la llamada.If the symbol is defined, the call is included; otherwise, the call is omitted. Usar Conditional es una alternativa más limpia, más elegante y menos propensa a generar errores para agregar métodos dentro de los bloques #if…#endif, como en el siguiente ejemplo:Using Conditional is a cleaner, more elegant, and less error-prone alternative to enclosing methods inside #if…#endif blocks, like this:

#if DEBUG  
    void ConditionalMethod()  
    {  
    }  
#endif  

Los métodos condicionales deben ser métodos de una declaración de clase o struct y no deben tener ningún valor devuelto.A conditional method must be a method in a class or struct declaration and must not have a return value.

Usar varios identificadoresUsing Multiple Identifiers

Si un método tiene varios atributos Conditional, se incluye una llamada al método si al menos uno de los símbolos condicionales está definido (es decir, si los símbolos están vinculados lógicamente entre sí mediante el operador OR).If a method has multiple Conditional attributes, a call to the method is included if at least one of the conditional symbols is defined (in other words, the symbols are logically linked together by using the OR operator). En este ejemplo, la presencia de A o de B dará como resultado una llamada al método:In this example, the presence of either A or B will result in a method call:

[Conditional("A"), Conditional("B")]  
static void DoIfAorB()  
{  
    // ...  
}  

Para lograr el efecto de una vinculación lógica de símbolos mediante el operador AND, puede definir métodos condicionales en serie.To achieve the effect of logically linking symbols by using the AND operator, you can define serial conditional methods. Por ejemplo, el segundo método que se muestra a continuación solo se ejecutará si tanto A como B están definidos:For example, the second method below will execute only if both A and B are defined:

[Conditional("A")]  
static void DoIfA()  
{  
    DoIfAandB();  
}  
  
[Conditional("B")]  
static void DoIfAandB()  
{  
    // Code to execute when both A and B are defined...  
}  

Usar Conditional con clases de atributosUsing Conditional with Attribute Classes

El atributo Conditional también se puede aplicar a una definición de clase de atributo.The Conditional attribute can also be applied to an attribute class definition. En este ejemplo, el atributo personalizado Documentation solo agregará información a los metadatos si se define DEBUG.In this example, the custom attribute Documentation will only add information to the metadata if DEBUG is defined.

[Conditional("DEBUG")]  
public class Documentation : System.Attribute  
{  
    string text;  
  
    public Documentation(string text)  
    {  
        this.text = text;  
    }  
}  
  
class SampleClass  
{  
    // This attribute will only be included if DEBUG is defined.  
    [Documentation("This method displays an integer.")]  
    static void DoWork(int i)  
    {  
        System.Console.WriteLine(i.ToString());  
    }  
}  

Atributos de información del llamadorCaller Info Attributes

Mediante los atributos de información del llamador, se puede obtener información sobre el llamador de un método.By using Caller Info attributes, you can obtain information about the caller to a method. Puede obtener la ruta de acceso al código fuente, el número de línea del código fuente y el nombre del miembro del llamador.You can obtain the file path of the source code, the line number in the source code, and the member name of the caller.

Para obtener la información del llamador del miembro, use los atributos que se aplican a los parámetros opcionales.To obtain member caller information, you use attributes that are applied to optional parameters. Cada parámetro opcional especifica un valor predeterminado.Each optional parameter specifies a default value. En la tabla siguiente se enumeran los atributos de información del llamador que se definen en el espacio de nombres System.Runtime.CompilerServices:The following table lists the Caller Info attributes that are defined in the System.Runtime.CompilerServices namespace:

AtributoAttribute DescripciónDescription TipoType
CallerFilePathAttribute Ruta de acceso completa del archivo de código fuente que contiene el llamador.Full path of the source file that contains the caller. Esta es la ruta de acceso en tiempo de compilación.This is the path at compile time. String
CallerLineNumberAttribute Número de línea del archivo de código fuente desde el que se llama al método.Line number in the source file from which the method is called. Integer
CallerMemberNameAttribute Nombre de método o de propiedad del llamador.Method name or property name of the caller. Para obtener más información, vea Caller Information (C#) (Información del llamador (C#)).For more information, see Caller Information (C#). String

Para obtener más información sobre los atributos de información del llamador, vea Caller Information (C#) (Información del llamador (C#)).For more information about the Caller Info attributes, see Caller Information (C#).

Vea tambiénSee also