Atributos comunes (C# y Visual Basic)
En este tema se describen los atributos que se utilizan con más frecuencia en los programas de C# y Visual Basic.
Atributos globales
Atributo Obsolete
Atributo Conditional
Atributos de información del llamador
Atributos de Visual Basic
Atributos globales
La mayoría de los atributos se aplican a elementos específicos del lenguaje, tales como clases o métodos; sin embargo, algunos atributos son globales, es decir, se aplican a todo un ensamblado o módulo. Por ejemplo, el atributo AssemblyVersionAttribute se puede utilizar para incrustar información de versión en un ensamblado, de la forma siguiente:
[assembly: AssemblyVersion("1.0.0.0")]
<Assembly: AssemblyVersion("1.0.0.0")>
Los atributos globales aparecen en el código fuente después de las directivas using (Imports en Visual Basic) de nivel superior y antes de las declaraciones de tipo, módulo o espacio de nombres. Los atributos globales pueden aparecer en varios archivos de código fuente, pero los archivos se deben compilar en un paso de compilación único. En los proyectos de Visual Basic, los atributos globales se colocan generalmente en el archivo AssemblyInfo.vb que se crea automáticamente con los proyectos de Visual Basic. En los proyectos de C#, se colocan en el archivo AssemblyInfo.cs.
Los atributos de ensamblado son valores que proporcionan información sobre un ensamblado. Se incluyen en las siguientes categorías:
Atributos de identidad de ensamblado
Atributos de información
Atributos del manifiesto del ensamblado
Atributos del nombre seguro
Atributos de identidad del ensamblado
Tres atributos (con un nombre seguro, si es aplicable) determinan la identidad de un ensamblado: nombre, versión y referencia cultural. Estos atributos forman el nombre completo del ensamblado y son necesarios para hacer referencia al ensamblado en el código. Puede establecerse una referencia cultural y una versión de ensamblado utilizando atributos. Sin embargo, el valor del nombre lo establece el compilador, el IDE de Visual Studio en el Información de ensamblado (Cuadro de diálogo) o la herramienta Assembly Linker (Al.exe) cuando se crea el ensamblado, tomando como base el archivo que contiene el manifiesto del ensamblado. El atributo AssemblyFlagsAttribute especifica si pueden coexistir varias copias del ensamblado.
La tabla siguiente muestra los atributos de identidad:
Atributo |
Objetivo |
|---|---|
Describe completamente la identidad del ensamblado. |
|
Especifica la versión del ensamblado. |
|
Especifica la referencia cultural admitida por el ensamblado. |
|
Especifica si un ensamblado admite ejecución conjunta en el mismo equipo, en el mismo proceso o en el mismo dominio de aplicación. |
Atributos informativos
Los atributos informativos se pueden usar para proporcionar información adicional del producto o de la compañía sobre un ensamblado. La tabla siguiente muestra los atributos de información definidos en el espacio de nombres System.Reflection.
Atributo |
Objetivo |
|---|---|
Define un atributo personalizado que especifica un nombre de producto para un manifiesto del ensamblado. |
|
Define un atributo personalizado que especifica una marca comercial para un manifiesto del ensamblado. |
|
Define un atributo personalizado que especifica una versión informativa para un manifiesto del ensamblado. |
|
Define un atributo personalizado que especifica un nombre de compañía para un manifiesto del ensamblado. |
|
Define un atributo personalizado que especifica un copyright para un manifiesto del ensamblado. |
|
Indica al compilador que debe utilizar un número de versión específico para el recurso de versión de archivo Win32. |
|
Indica si el ensamblado cumple los requisitos de Common Language Specification (CLS). |
Atributos de manifiesto del ensamblado
Puede usar los atributos del manifiesto del ensamblado para proporcionar información en el manifiesto del ensamblado. Esto incluye título, descripción, alias predeterminado y configuración. La tabla siguiente muestra los atributos del manifiesto del ensamblado definidos en el espacio de nombres System.Reflection.
Atributo |
Objetivo |
|---|---|
Define un atributo personalizado que especifica un título de ensamblado para un manifiesto del ensamblado. |
|
Define un atributo personalizado que especifica una descripción de ensamblado para un manifiesto del ensamblado. |
|
Define un atributo personalizado que especifica una configuración de ensamblado (como versión comercial o de depuración) para un manifiesto del ensamblado. |
|
Define un alias predeterminado descriptivo para un manifiesto del ensamblado |
Atributos del nombre seguro
En versiones anteriores de Visual Studio, la firma de ensamblados utilizando nombres seguros se realizaba con estos atributos de nivel de ensamblado:
Esto se sigue admitiendo, pero la forma preferida de firmar los ensamblados es utilizar la Página de firma del Diseñador de proyectos. Para obtener más información, vea Página Firma, Diseñador de proyectos y Cómo: Firmar un ensamblado (Visual Studio).
Atributo Obsolete
El atributo Obsolete marca una entidad del programa como si su uso ya no estuviera recomendado. Cada uso de una entidad marcada obsoleta generará en consecuencia una advertencia o un error, dependiendo de la configuración del atributo. Por ejemplo:
<System.Obsolete("use class B")>
Class A
Sub Method()
End Sub
End Class
Class B
<System.Obsolete("use NewMethod", True)>
Sub OldMethod()
End Sub
Sub NewMethod()
End Sub
End Class
[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. Como el segundo argumento del constructor del atributo aplicado a B.OldMethod se establece en true, este método generará un error de compilación, mientras que el uso de la clase A sólo generará una advertencia. Sin embargo, llamar a B.NewMethod no genera ninguna advertencia o error.
La cadena proporcionada como primer argumento al constructor de atributos se mostrará como parte de la advertencia o error. Por ejemplo, cuando lo use con las definiciones anteriores, el código siguiente genera dos advertencias y un error:
' Generates 2 warnings:
' Dim a As New A
' Generate no errors or warnings:
Dim b As New B
b.NewMethod()
' Generates an error, terminating compilation:
' b.OldMethod()
// 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: uno para la declaración de la referencia de clase y otro para el constructor de clase.
El atributo Obsolete se puede utilizar sin argumentos, pero incluyendo una explicación del motivo por el que el elemento está obsoleto y una recomendación sobre qué utilizar en su lugar.
Obsolete es un atributo de un solo uso y puede aplicarse a cualquier entidad que permita atributos. Obsolete es un alias de ObsoleteAttribute.
Atributo Conditional
El atributo Conditional realiza la ejecución de un método que depende de un identificador de preprocesamiento. El atributo Conditional es un alias de ConditionalAttribute y se puede aplicar a un método o a una clase de atributos.
En este ejemplo, Conditional se aplica a un método para habilitar o deshabilitar la presentación de información de diagnóstico específica del programa:
#Const TRACE_ON = True
Imports System
Imports System.Diagnostics
Module TestConditionalAttribute
Public Class Trace
<Conditional("TRACE_ON")>
Public Shared Sub Msg(ByVal msg As String)
Console.WriteLine(msg)
End Sub
End Class
Sub Main()
Trace.Msg("Now in Main...")
Console.WriteLine("Done.")
End Sub
End Module
#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 no se define el identificador TRACE_ON, no se mostrará ningún resultado de seguimiento.
El atributo Conditional se utiliza a menudo con el identificador DEBUG para habilitar las características de rastreo y registro en las versiones de depuración, pero no en las versiones de lanzamiento, como se indica a continuación:
<Conditional("DEBUG")>
Shared Sub DebugMethod()
End Sub
[Conditional("DEBUG")]
static void DebugMethod()
{
}
Cuando se llama a un método marcado como condicional, la presencia o ausencia del símbolo de preprocesamiento especificado determina si la llamada se incluye o se omite. Si el símbolo se define, la llamada se incluye; en caso contrario, la llamada se omite. El uso de Conditional es una alternativa más limpia, más elegante y menos propensa a errores que la inclusión de métodos dentro de bloques #if…#endif, como se indica a continuación:
#If DEBUG Then
Sub ConditionalMethod()
End Sub
#End If
#if DEBUG
void ConditionalMethod()
{
}
#endif
Un método condicional debe ser un método en una declaración de clase o de struct y no debe tener un valor devuelto.
Usar varios identificadores
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, los símbolos están vinculados entre sí de forma lógica mediante el uso del operador OR). En este ejemplo, la presencia de A o de B tendrá como resultado la llamada a un método:
<Conditional("A"), Conditional("B")>
Shared Sub DoIfAorB()
End Sub
[Conditional("A"), Conditional("B")]
static void DoIfAorB()
{
// ...
}
Para conseguir el efecto de vinculación lógica de símbolos mediante el uso del operador AND, se pueden definir métodos condicionales en serie. Por ejemplo, el segundo método que se expone a continuación sólo se ejecutará si se definen A y B:
<Conditional("A")>
Shared Sub DoIfA()
DoIfAandB()
End Sub
<Conditional("B")>
Shared Sub DoIfAandB()
' Code to execute when both A and B are defined...
End Sub
[Conditional("A")]
static void DoIfA()
{
DoIfAandB();
}
[Conditional("B")]
static void DoIfAandB()
{
// Code to execute when both A and B are defined...
}
Uso de Conditional con clases de atributos
El atributo Conditional también se puede aplicar a una definición de clase de atributos. En este ejemplo, el atributo personalizado Documentation sólo agregará información a los metadatos si se define DEBUG.
<Conditional("DEBUG")>
Public Class Documentation
Inherits System.Attribute
Private text As String
Sub New(ByVal doc_text As String)
text = doc_text
End Sub
End Class
Class SampleClass
' This attribute will only be included if DEBUG is defined.
<Documentation("This method displays an integer.")>
Shared Sub DoWork(ByVal i As Integer)
System.Console.WriteLine(i)
End Sub
End Class
[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 llamador
Mediante los atributos de información del llamador, se puede obtener información sobre el autor de la llamada a un método. Se puede obtener la ruta de acceso al código fuente, el número de línea en el código fuente y el nombre de miembro del llamador.
Para obtener información del llamador del miembro, se usan los atributos que se aplican a los parámetros opcionales. Cada parámetro opcional especifica un valor predeterminado. La tabla siguiente enumera los atributos de la información del llamador que se definen en el espacio de nombres System.Runtime.CompilerServices:
Atributo |
Descripción |
Tipo |
Ruta de acceso completa del archivo de código fuente que contiene el llamador. Esta es la ruta de acceso en tiempo de compilación. |
String |
|
Número de línea en el archivo de código fuente desde el que se llama al método. |
Integer |
|
Nombre del método o nombre de propiedad del llamador. Para obtener más información, vea Información del llamador (C# y Visual Basic). |
String |
Para obtener más información sobre el llamador de atributos de información, consulte Información del llamador (C# y Visual Basic).
Atributos de Visual Basic
En la tabla siguiente se enumeran los atributos que son específicos de Visual Basic.
Atributo |
Objetivo |
|---|---|
Indica al compilador que la clase debe exponerse como un objeto COM. |
|
Permite tener acceso a los miembros de módulo utilizando sólo la calificación necesaria para el módulo. |
|
Especifica el tamaño de una cadena de longitud fija en una estructura para utilizarla con funciones de entrada y salida de archivos. |
|
Especifica el tamaño de una matriz de tamaño fijo en una estructura para utilizarla con funciones de entrada y salida de archivos. |
COMClassAttribute
Use COMClassAttribute para simplificar el proceso de creación de componentes COM desde Visual Basic. Los objetos COM son considerablemente distintos de los ensamblados de .NET Framework y, sin COMClassAttribute, es necesario seguir una serie de pasos para generar un objeto COM desde Visual Basic. Para las clases marcadas con COMClassAttribute, el compilador ejecuta muchos de estos pasos automáticamente.
HideModuleNameAttribute
Utilice HideModuleNameAttribute para permitir el acceso a los miembros de módulo utilizando solamente la calificación necesaria para el módulo.
VBFixedStringAttribute
Utilice VBFixedStringAttribute para obligar a Visual Basic a crear una cadena de longitud fija. Las cadenas son de longitud variable de forma predeterminada y este atributo resulta útil cuando se almacenan cadenas en archivos. El código siguiente describe esto:
Structure Worker
' The runtime uses VBFixedString to determine
' if the field should be written out as a fixed size.
<VBFixedString(10)> Public LastName As String
<VBFixedString(7)> Public Title As String
<VBFixedString(2)> Public Rank As String
End Structure
VBFixedArrayAttribute
Utilice VBFixedArrayAttribute para declarar matrices de tamaño fijo. Al igual que las cadenas de Visual Basic, las matrices son de longitud variable de forma predeterminada. Este atributo resulta de utilidad cuando se serializan o se escriben datos a archivos.
Vea también
Referencia
Obtener acceso a los atributos mediante la reflexión (C# y Visual Basic)