ET has more than 100 attributes that are used to control XML serialization, Web services, COM interoperability, and more. For example, XmlElementAttribute is used to control the element name and data type used when serializing a class to XML, and AssemblyVersionAttribute is used to assign a version number to an assembly.
But you aren’t limited to using the ones that Microsoft built. Custom attributes allow the developer to store meta-data against program elements, and that data can be accessed at runtime to control program actions. This article will show you how to create your own custom attributes in .NET and will give you a practical example of how to use them.
Creating Your Own Attributes
To create your own custom attribute class, simply create a new class that inherits System.Attribute. Add whatever properties you want (normally you will also add these to your attribute class constructor), and your custom attribute class is ready for use.
The next step is to determine what elements your attribute can be used on. By default, custom attributes can be applied to all program elements. But you can restrict which types of program elements your custom attribute can be applied to by using the AttributeUsage attribute. The constructor for AttributeUsage takes an enumeration argument of type AttributeTargets (this enumeration is a bit mask, so you can combine values with a bitwise or operation).
You can use the other arguments to AttributeUsage to control whether multiple instances of the same attribute are allowed, and whether derived classes inherit your custom attribute. For example, you could use these arguments to define a custom attribute that can be used with a property only, is inherited by derived classes, and can be used only once for each property use. The code to implement those conditions is shown:
< _ System.AttributeUsage( _ System.AttributeTargets.Property, _ AllowMultiple:=False, _ Inherited:=True) _ > _ Public Class ListDisplayAttribute Inherits System.Attribute ' Code goes here End Class
Using Attributes in Code
Attributes can be applied to many elements in .NET code, including assemblies, classes, properties, events, and enumerations. This code demonstrates the same attribute, MonitoringDescription, applied to a class and to a property.
_Public Class TestClass _ Public ReadOnly Property TestProp() As String Get End Get End PropertyEnd Class
By convention, classes that inherit from System. Attribute have an “Attribute” suffix added to their names, as in Diagnostics.MonitoringDescriptionAttribute, above. You can use the class name without the “Attribute” suffix when you use attributes in code. In the example above, I used MonitoringDescription on the class and MonitoringDescriptionAttribute on the property. Both are interpreted the same way. This can be a bit confusing because if you are looking for help in the .NET framework documentation, you have to use the “real” class name?that is, use MonitoringDescriptionAttribute when you search or you won’t find the help topic you are looking for.
Reading Custom Attributes at Runtime
To read the value of a custom attribute, call the GetCustomAttributes function of the MemberInfo class. (The MemberInfo class is inherited by EventInfo, FieldInfo, MethodBase, PropertyInfo, and System.Type, and is therefore available from most of the reflection objects).
The GetCustomAttributes function returns an array of Attribute objects. You should always check to make sure that at least one item is in the returned array. It is possible to define the same attribute multiple times on an element, and not all elements will have the attribute defined that you are searching for, so GetCustomAttributes can return an array with multiple results, or an empty array.
This code displays the assembly title of the executing assembly by reading the assembly’s AssemblyTitle attribute value.
Dim objAttrSet() As System.Reflection.AssemblyTitleAttributeobjAttrSet = _ Reflection.Assembly.GetExecutingAssembly.GetCustomAttributes( _ GetType(System.Reflection.AssemblyTitleAttribute), False)If objAttrSet.Length = 0 Then MsgBox("No Assembly Title attribute was found!")Else MsgBox(objAttrSet(0).Title)End If
This example reads a custom attribute of a class.
Dim objAttrSet() As System.Diagnostics.MonitoringDescriptionAttributeobjAttrSet = _ Me.GetType.GetCustomAttributes( _ GetType(System.Diagnostics.MonitoringDescriptionAttribute), False)If objAttrSet.Length = 0 Then MsgBox("No MonitoringDescription attribute was found!")Else MsgBox(objAttrSet(0).Title)End If
Implementation ideas?Automatic List View
The sample code for this article uses reflection and custom attributes to automatically populate a list view’s column headers for a specified object type. The code contains:
- A form containing an instance of our derived list view and some sample code to populate it.
- Our custom attribute class, ListDisplayAttribute.
- Our derived listview class. This class adds two methods, SetType(), which populates the list view’s column headers collection, and AddItem(), which adds a ListViewItem to the list view, automatically populating the subitems collection for that ListViewItem.
- A sample class for holding data called SampleContactObject. This class contains four properties: “name,” “password,” “email,” and “telephone.” This class contains examples of the use of the ListDisplay Attribute.
The ListDisplayAttribute class is pretty straightforward?it is derived from System.Attribute and contains three properties:
Determines whether to display the property in a list view column
The text to place in the column header
The width to assign to the column header
Our derived list view class has a GetProperties to get a PropertyInfo object that represents each property in the type.
|Author’s Note: The code example has been simplified. Download the full version of the code by clicking the “download the code” link in the left column.)|
' Loop through all the properties in the object For Each prpObjectProperty In mtypListItemType.GetProperties ' Add column headers If prpObjectProperty.GetCustomAttributes( _ GetType(Devx.ListDisplayAttribute), True).Length = 0 Then ' Set default properties Else ' Attribute found attListAttribute = prpObjectProperty.GetCustomAttributes( _ GetType(Devx.ListDisplayAttribute), True)(0) ' read values blnShowColumn = attListAttribute.Display intWidth = attListAttribute.DefaultWidth ' The header text is not always specified, so we need ' to use the property name if it is left blank. strHeader = attListAttribute.ColumnText If strHeader.Length = 0 Then strHeader = prpObjectProperty.Name End If End If Next
Inside the loop, I call GetCustomAttributes, check that it returns at least one result, and then read the Display, DefaultWidth, and ColumnText properties into variables used elsewhere in the code.
You can create generic code that uses “self-describing” program elements using reflection and custom attributes. I’ve used this technique to create generic classes that read and write themselves to database tables and am experimenting with self-documenting code, just to give a couple of examples. There are many uses for this technique, limited only by your requirements and imagination.