Section 8.1. Syntax and Use

8.1 Syntax and Use

In Visual Basic, an attribute appears within angle brackets (a less-than (<) and a greater-than symbol (>)). The attribute name is followed by parentheses, which are used to enclose arguments that might be passed to the attribute. For example, the <Obsolete> attribute marks a type or type member as obsolete. We can apply <Obsolete> as a parameter-less attribute as follows :

 <Obsolete(  )> 

If no arguments are assigned to the attribute, we can omit the trailing parentheses:

 <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 by a comma. For example:

 <Obsolete(), WebMethod(  )> Public Function PageCount( _                           strURL As String) As Integer 

Each attribute corresponds to a class derived from System.Attribute. (In fact, the VB.NET compiler actually treats an attribute as an instance of the attribute's class.) By convention, we drop the trailing string "Attribute" from the class name to form the attribute name, although the attribute name can also be identical to the class name. Thus, for example, the <WebMethod> attribute corresponds to the WebMethodAttribute class in the System.Web.Services namespace, which in turn is found in System.Web.Services.dll . Alternately, you can also specify the attribute as <WebMethodAttribute> . If the namespace containing the attribute class is not automatically accessible to the Visual Basic compiler or to Visual Studio, the Imports directive should be used, and a reference should be added to the project either using the References dialog in Visual Studio or the /r switch in the command-line compiler.

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

 <ParamArray(  )> lScores As Long) 

However, the following code compiles correctly:

 <ParamArrayAttribute(  )> lScores As Long) 

The attribute class constructor or 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) 

Hence, the <VBFixedString> attribute can be used as follows:

 <VBFixedString(10)> Private sID As String 

Attribute constructors can be overloaded. Any required arguments must correspond to those expected by one of the constructors in number and data type.

Required arguments must be supplied to the attribute as positional arguments only ; named arguments are not accepted. A comma separates all arguments, whether named or positional.

Optional arguments correspond to class properties and can be supplied to the attribute as named arguments. For example, in addition to its constructor, which indicates to what language elements the attribute applies, the <AttributeUsage> attribute, which is used to define the language elements to which a custom attribute applies, has a Boolean property, Inherited, that indicates whether the attribute is inherited by derived classes and overridden members . Its default value is True . To set it to False , you could use the attribute as follows:

 <AttributeUsage(AttributeTargets.Class, Inherited:=False)> _ Public Class MyCustomClass 

Be sure to recognize that 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 the attribute's constructor.

Unless it has a modifier, an attribute immediately precedes the language element to which it applies and must be on the same logical line as that language element. If they are on different lines, the Visual Basic .NET line continuation character (the underscore , or _ ) must be used. This syntax is valid for attributes applied to the following language elements:

Class

Constructor

Delegate

Enum

Event

Field

Interface

Method

Parameter

Property

Return Value

Structure

For example, the following Class statement illustrates this general usage of an attribute:

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

The following statement indicates how attributes are used with parameter declarations:

 Public Sub MyFunction(strName As String, _                       <ParamArrayAttribute(  )> lValues As Long) 

There are two exceptions to this rule. Some attributes must be prefaced with a modifier (either Assembly: or Module: ) indicating the program element to which the attribute applies. In that case, the attribute must be placed at the top of the source file (i.e., immediately following any Option and Imports statements), along with any other attributes that require a modifier. This syntax is valid for an attribute applied to an assembly or a module only.

For example:

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