Udostępnij za pośrednictwem


Application of Attributes

You apply attributes by adding attribute blocks to program elements such as properties, methods, events, classes, and assemblies. An attribute block consists of angle brackets ("< >") enclosing a list of comma-separated attribute declarations. An attribute declaration consists of an optional attribute modifier such as Module or Assembly, an attribute name, a (possibly overloaded) list of required positional parameters, and a list of optional named arguments. You must place attributes with modifiers in an attributes section at the top of a source file. For example, the following code sets an assembly attribute that defines a title for the assembly, and a module attribute that indicates that the module is compliant with the common language specification (CLS):

Imports System.Reflection
<Assembly: AssemblyTitleAttribute("Production assembly 4"), _
Module: CLSCompliant(True)> 

Assembly attributes also can be applied by means of the AssemblyInfo.vb file, which is added to projects automatically by the Visual Studio user interface. This file contains assembly-level attributes with either default or empty values.

When applied to program elements such as properties, attributes precede the element. For example, the following code applies an attribute to a class definition:

<CustomAttr(Update:=True)> Class Class1

By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET Framework. However, you do not need to specify the attribute suffix when using attributes. For example, if you had an attribute named CustomAttrAttribute, then specifying <CustomAttr(Update:=True)> is equivalent to specifying <CustomAttrAttribute(Update:=True)>.

Attribute Arguments

Attributes use optional, required, positional, and named arguments in much the same way that objects use these types of arguments. Positional arguments are arguments that are specified in the order they are declared for the constructor of an attribute. For example, the following code calls the Sub New constructor of an attribute with two values:

<CustomAttr(True, False)> Class Class1

Arguments passed to Sub New in attribute classes are often used to initialize the values of fields and properties.

You can use named arguments to directly set the value of properties and fields. You specify a named argument by appending ":=" to the name of the argument, followed by the value being specified. Unlike positional arguments, named arguments can be specified in any order. For example, the following code sets the value True for the Update field, and False for the Keep field:

<CustomAttr(Update:=True, Keep:=False)> Class Class1

Note

Attribute arguments have one important difference from arguments used with standard method calls. You must use positional arguments for arguments that are used with the Sub New constructor of attribute classes. Named arguments can only be used to set the values of fields and properties of attribute classes.

Required arguments are those that must always be specified. Optional arguments are those that can be skipped using a comma as a placeholder (when using positional arguments), or simply omitted (when using named arguments).

Attribute arguments must be constant expressions.

Attribute Examples

The following procedures provide examples of attribute declarations.

To use the MarshalAs attribute to control how parameters are marshaled

  1. Add an Imports statement for the System.Runtime.InteropServices namespace to the top of your source code:

    Imports System.Runtime.InteropServices
    
  2. Prefix parameters with the MarshalAsAttribute attribute and specify the data type the target requires. For example, the following code marshals two parameters as the data type long pointer to a string (LPStr) for a Windows API function:

    Declare Auto Sub CopyFile Lib "Kernel32.Lib" ( _
       <MarshalAs(UnmanagedType.LPWStr)> ByVal existingfile As String, _
       <MarshalAs(UnmanagedType.LPWStr)> ByVal newfile As String, _
       ByVal failifexists As Boolean _
    )
    

The common language runtime uses the MarshalAsAttribute attribute to determine how a parameter should be marshaled between the managed code of Visual Basic and the unmanaged code in a Windows API call.

To expose a method to remote Web clients

  1. From the File menu, click Project, select the ASP.NET Web Service template, and add an Imports statement for the System.Web namespace:

    Imports System.Web.Services
    
  2. Define a method and use the WebMethodAttribute attribute to make it callable from remote Web clients:

    <WebMethod()> Public Function HelloWorld() As String
        HelloWorld = "Hello World..." 
    End Function
    

Making an XML Web service method Public is not sufficient to expose it to Web clients. You must explicitly apply the WebMethodAttribute attribute to a method before it can be called by a remote Web client.

See Also

Tasks

How to: Define Your Own Attributes

Concepts

Attributes Overview in Visual Basic

Common Uses for Attributes

Passing Arguments by Position and by Name

Reference

WebMethodAttribute

Imports Statement (.NET Namespace and Type)

MarshalAsAttribute

System.Web

Other Resources

Custom Attributes in Visual Basic