Compartir vía

Common Attributes (Visual Basic) (Atributos comunes [Visual Basic])

  • Artículo

En este tema se describen los atributos que más se usan en los programas de Visual Basic.

Atributos globales

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). Por ejemplo, el atributo AssemblyVersionAttribute se puede usar para insertar información de versión en un ensamblado, como en este ejemplo:

<Assembly: AssemblyVersion("1.0.0.0")>

Los atributos globales aparecen en el código fuente después de cualquier instrucción Imports de nivel superior y antes de cualquier declaración de tipo, módulo o espacio de nombres. 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. En el caso de los proyectos de Visual Basic, los atributos globales suelen colocarse en el archivo AssemblyInfo.vb (el archivo se crea automáticamente al crear un proyecto en Visual Studio).

Los atributos de ensamblado son valores que proporcionan información sobre un ensamblado. Se dividen en las siguientes categorías:

  • Atributos de identidad del ensamblado

  • Atributos informativos

  • Atributos de manifiesto del ensamblado

Atributos de identidad del ensamblado

Tres atributos, con un nombre seguro (si procede), determinan la identidad de un ensamblado: nombre, versión y referencia cultural. Estos atributos forman el nombre completo del ensamblado y son necesarios cuando se hace referencia a este en el código. Puede establecer la versión y la referencia cultural de un ensamblado mediante atributos, 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. El atributo AssemblyFlagsAttribute especifica si pueden coexistir varias copias del ensamblado.

En la siguiente tabla se muestran los atributos de identidad.

Atributo Propósito
AssemblyName Describe completamente la identidad de un ensamblado.
AssemblyVersionAttribute Especifica la versión de un ensamblado.
AssemblyCultureAttribute Especifica la cultura que admite el ensamblado.
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.

Atributos informativos

Puede utilizar atributos informativos para proporcionar información adicional de la compañía o de producto para un ensamblado. En la tabla siguiente se muestran los atributos informativos definidos en el espacio de nombres System.Reflection.

Atributo Propósito
AssemblyProductAttribute Define un atributo personalizado que especifica un nombre de producto para un manifiesto del ensamblado.
AssemblyTrademarkAttribute Define un atributo personalizado que especifica una marca comercial para un manifiesto del ensamblado.
AssemblyInformationalVersionAttribute Define un atributo personalizado que especifica una versión informativa para un manifiesto del ensamblado.
AssemblyCompanyAttribute Define un atributo personalizado que especifica un nombre de compañía para un manifiesto del ensamblado.
AssemblyCopyrightAttribute Define un atributo personalizado que especifica un copyright para un manifiesto del ensamblado.
AssemblyFileVersionAttribute Indica al compilador que use un número de versión específico para el recurso de versión de archivo Win32.
CLSCompliantAttribute Indica si el ensamblado es compatible con Common Language Specification (CLS).

Atributos de manifiesto del ensamblado

Puede usar los atributos de manifiesto del ensamblado para proporcionar información en el manifiesto del ensamblado (título, descripción, alias predeterminado y configuración). En la tabla siguiente se muestran los atributos de manifiesto del ensamblado definidos en el espacio de nombres System.Reflection.

Atributo Propósito
AssemblyTitleAttribute Define un atributo personalizado que especifica un título de ensamblado para un manifiesto del ensamblado.
AssemblyDescriptionAttribute Define un atributo personalizado que especifica una descripción de ensamblado para un manifiesto del ensamblado.
AssemblyConfigurationAttribute Define un atributo personalizado que especifica una configuración de ensamblado (por ejemplo, comercial o depuración) para un manifiesto del ensamblado.
AssemblyDefaultAliasAttribute Define un alias descriptivo predeterminado para un manifiesto del ensamblado.

Atributo obsoleto

El atributo Obsolete marca una entidad del programa como una entidad cuyo uso ya no se recomienda. Cada uso de una entidad marcada como obsoleta generará posteriormente una advertencia o un error, en función 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

En este ejemplo, el atributo Obsolete se aplica a la clase A y al método 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. En cambio, si se llama a B.NewMethod, no se generará 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, al usarla 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()

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.

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.

El atributo Obsolete es un atributo de uso único y se puede aplicar a cualquier entidad que admita atributos. Obsolete es un alias de ObsoleteAttribute.

Atributo Conditional

El atributo Conditional hace que la ejecución de un método dependa 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 atributo.

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:

#Const TRACE_ON = True
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

Si el identificador TRACE_ON no está definido, no se mostrará ningún resultado del seguimiento.

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:

<Conditional("DEBUG")>
Shared Sub DebugMethod()

End Sub

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. Si el símbolo está definido, se incluye la llamada; de lo contrario, se omite la llamada. 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:

#If DEBUG Then
    Sub ConditionalMethod()
    End Sub
#End If

Los métodos condicionales deben ser métodos de una declaración de clase o struct y no deben tener ningún 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, si los símbolos están vinculados lógicamente entre sí mediante el operador OR). En este ejemplo, la presencia de A o de B dará como resultado una llamada al método:

<Conditional("A"), Conditional("B")>
Shared Sub DoIfAorB()

End Sub

Para lograr el efecto de una vinculación lógica de símbolos mediante el operador AND, puede definir métodos condicionales en serie. Por ejemplo, el segundo método que se muestra a continuación solo se ejecutará si tanto A como B están definidos:

<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

Usar Conditional con clases de atributos

El atributo Conditional también se puede aplicar a una definición de clase de atributo. En este ejemplo, el atributo personalizado Documentation solo 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

Atributos de información del llamador

Mediante los atributos de información del llamador, se puede obtener información sobre el llamador de un método. 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.

Para obtener la información del llamador del miembro, use los atributos que se aplican a los parámetros opcionales. Cada parámetro opcional especifica un valor predeterminado. En la tabla siguiente se enumeran los atributos de información del llamador que se definen en el espacio de nombres System.Runtime.CompilerServices:

Atributo Descripción Tipo
CallerFilePathAttribute 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
CallerLineNumberAttribute Número de línea del archivo de código fuente desde el que se llama al método. Integer
CallerMemberNameAttribute Nombre de método o de propiedad del llamador. Para obtener más información, consulta Información del llamador (Visual Basic). String
CallerArgumentExpressionAttribute Expresión usada por el autor de la llamada para un argumento. Para obtener más información, consulta Información del llamador (Visual Basic). String

Para obtener más información sobre los atributos de información del llamador, vea Información del llamador (Visual Basic).

Atributos de Visual Basic

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

Atributo Propósito
ComClassAttribute Indica al compilador que la clase debe exponerse como un objeto COM.
HideModuleNameAttribute Permite que se acceda a los miembros del módulo solo con la calificación necesaria para el módulo.
VBFixedStringAttribute Especifica el tamaño de una cadena de longitud fija en una estructura para su uso con funciones de entrada y salida de archivos.
VBFixedArrayAttribute Especifica el tamaño de una matriz fija en una estructura para su uso con funciones de entrada y salida de archivos.

COMClassAttribute

Usa COMClassAttribute para simplificar el proceso de creación de componentes COM desde Visual Basic. Los objetos COM son considerablemente diferentes de los ensamblados de .NET Framework y, sin COMClassAttribute, debes seguir varios pasos para generar un objeto COM a partir de Visual Basic. En el caso de las clases marcadas con COMClassAttribute, el compilador realiza muchos de estos pasos automáticamente.

HideModuleNameAttribute

Usa HideModuleNameAttribute para permitir que se acceda a los miembros del módulo solo con la calificación necesaria para el módulo.

VBFixedStringAttribute

Usa VBFixedStringAttribute para forzar a Visual Basic a crear una cadena de longitud fija. Las cadenas son de longitud variable de forma predeterminada y este atributo es útil al almacenar cadenas en archivos. El código siguiente muestra este proceso:

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

Usa VBFixedArrayAttribute para declarar matrices que tienen un tamaño fijo. Al igual que las cadenas de Visual Basic, las matrices tienen una longitud variable de forma predeterminada. Este atributo es útil al serializar o escribir datos en archivos.

Consulte también