Section 9.1. Syntax and Use

9.1. Syntax and Use

In Visual Basic, an attribute appears within angle brackets (< and >) immediately before the type or type member that it modifies. The attribute name is followed by parentheses, which enclose a comma-delimited list of arguments to be passed to the attribute. For example, the <Obsolete> attribute marks a type or type member as obsolete. One of its optional arguments is a warning message to be passed on to anyone interested. Apply the <Obsolete> attribute with a message as follows:

     <Obsolete("Don't even think of using this feature.")> 

If there are no arguments, or none that you wish to include, just use empty parentheses:

     <Obsolete(  )> 

or remove the parentheses completely:

     <Obsolete> 

If more than one attribute is applied to a single program element, the attributes are enclosed in a single set of angle brackets and delimited from one another with commas.

     <Obsolete, WebMethod> Public Function PageHitCount( _           baseURL As String) As Integer 

Each attribute corresponds to a class derived from System.Attribute. In fact, the VB compiler actually treats an attribute as an instance of the attribute's class. If you look in the .NET documentation, you will recognize attribute classes by the word "Attribute" on the end of their class names. For instance, the Obsolete attribute comes from the ObsoleteAttribute class. It's a good idea to include the word "Attribute" on any attribute classes you create yourself. However, when you use an attribute (within angle brackets), you can omit the trailing word "Attribute" if you want, just to keep things short. The compiler will add "Attribute" back in, if needed.

If the shortened attribute name is a Visual Basic keyword, use the attribute's full class name to prevent a compiler error. For example, the following declaration produces an error because ParamArray is a Visual Basic keyword:

     <ParamArray> scores As Long 

The following code compiles correctly:

     <ParamArrayAttribute> scores As Long 

An attribute's class constructors determine whether any arguments are required. For example, the <VBFixedString> attribute corresponds to the VBFixedStringAttribute class, which has the following constructor:

     New(ByVal size As Integer) 

The <VBFixedString> attribute can be used as follows:

     <VBFixedString(10)> Private customerID As String 

Attribute constructors can be overloaded. The argument signature you use must correspond to one of the constructor signatures for that attribute.

Arguments passed to an attribute can be positional or named. Positional arguments appear in the same comma-separated position that is defined in the associated constructor. Named arguments can appear out of order, but they must be preceded by the argument name and the := association operator. Required arguments to a constructor must be positional. Optional arguments can be named or positional, but they must appear after all required arguments. Attribute class properties can be set using named arguments . For instance, the <WebMethod> attribute includes a Description property that can be set as a named argument.

     <WebMethod(Description:="Page use counter")> _     Public Function PageHitCount(baseURL As String) As Integer 

Attributes are evaluated at compile time, when their data is written to the assembly's metadata. This means that only literal values can be passed as arguments to an attribute's constructor, and not variables.

When you use .NET classes in your application, you need to indicate where they reside in the namespace hierarchy, either explicitly with each use or implicitly by using the Imports keyword. Since attributes are just classes, you have to indicate their location as well. If an attribute is not in one of the already loaded namespaces (like System), you can use Imports in the file where you make use of the attribute and set a reference to it in Visual Studio or on the compiler command line.

An attribute immediately precedes the language element to which it applies (and that element's modifiers, like Public), and it must be on the same logical line as that language element. Use the standard line continuation character (the underscore, "_") to join multiple physical lines into a single logical line, if desired.

Attributes can be applied to the following language elements:

Class

Constructor (methods with the name "New")

Delegate

Enum

Event

Field

Interface

Method

Parameter (of a procedure)

Property

Return value (of a procedure)

Structure

For example, the <AttributeUsage> attribute comes before Class statements.

     <AttributeUsage(AttributeTargets.All)> _     Public Class MyCustomAttrAttribute 

The <ParamArrayAttribute> attribute comes just before the final parameter in a procedure's parameter list.

     Public Sub MyProcedure(baseAction As String, _           <ParamArrayAttribute> actionValues As Long) 

Attributes that are designed to decorate either an assembly or a module both appear at the top of a source code file (just after any Option or Imports statements). To avoid confusion, these attributes must be prefixed with a modifier (either Assembly: or Module:) indicating the program element to modify. For example:

     Option Strict On     Imports System.Data.SqlClient     <Assembly: AssemblyDescription("Supplementary data access library")>     Namespace SqlAccess     ...