How to: Provide Metadata Descriptions About Your Component

You can provide descriptive metadata about your component through attributes. Attributes are specialized classes that are applied to code elements. At compile time, attributes are emitted into metadata that is available to the common language runtime or to custom tools and applications through the System.Reflection namespace.

Attributes are attached to a component by preceding the component with a reference to the attribute and providing any relevant parameters or flags. This call to the constructor is placed within angle brackets <> in Visual Basic and regular brackets [] in C#.

By convention, all attribute classes end in "Attribute." For example, there are DescriptionAttribute, ObsoleteAttribute, and BrowsableAttribute classes. However, several languages that target the common language runtime, including Visual Basic and C#, do not require the full name of the attribute. For example, the ObsoleteAttribute may be referred to in code as Obsolete.

To attach an existing attribute to your component

  1. Determine which attributes are required for your component.

  2. Attach the attributes to your component. Note that you must either use the fully qualified name of the attribute or add the appropriate Imports (using) statement. The following example shows how to attach the DescriptionAttribute attribute:

    Imports System.ComponentModel
    <Description("This is a description string")> Public Class TheClass
    End Class

You can also create your own attributes for use with your own custom tools or applications by inheriting from Attribute. You can add to this base class any custom properties or methods needed by your application.

To create and apply a custom attribute

  1. Create a class that inherits from Attribute.

    Public Class WidgetAttribute
       Inherits System.Attribute
    End Class
  2. Determine which properties and methods your attribute needs and write the code for them. The following example shows how to create a WidgetType property that is set in the constructor of the WidgetAttribute class. TheAttributeUsageAttribute attribute sets what code members the attribute can target.

    <AttributeUsage(System.AttributeTargets.Class)> Public Class _
       Inherits System.Attribute
       Private mWidgetType as WidgetTypeEnum
       ' Creates a readonly property for the WidgetAttribute class.
       Public ReadOnly Property WidgetType as WidgetTypeEnum
             Return mWidgetType
          End Get
       End Property
       ' Creates a constructor that accepts a parameter and assigns the 
       ' value of that parameter to the WidgetType property.
       Public Sub New(type as WidgetTypeEnum)
          mWidgetType = type
       End Sub
    End Class
  3. Apply this attribute as you would any other attribute, being certain to apply any needed parameters.

    <WidgetAttribute(WidgetTypeEnum.VerticalWidget)> _
       Public Class WidgetFortyFive
    End Class