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 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 de 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:

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.

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 de ensamblado definidos en el espacio de nombres System.Reflection.

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:

• AssemblyKeyFileAttribute

• AssemblyKeyNameAttribute

• AssemblyDelaySignAttribute

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 Visual Basic

En la tabla siguiente se enumeran los atributos que son específicos de Visual Basic.

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

Reflexión (C# y Visual Basic)

Obtener acceso a los atributos mediante la reflexión (C# y Visual Basic)

System.Reflection

Attribute

Conceptos

Guía de programación de C#

Extender metadatos mediante atributos

Otros recursos

Guía de programación en Visual Basic