[.NET 2.0+] Displaying Friendly Names for Enumerations

[jmcilhinney]

C# version here.

I've seen information on this technique in several places, possibly even on this forum. I've extended what I've read by creating a couple of classes that make displaying friendly names easier.

First, a bit of background. Enumerations, created in VB with the Enum key word, are lists of text values that each correspond to a number. They are used to provide a limited list of possible values. We use them in many situations, for instance the DialogResult values that are returned by MessageBox.Show are members of the DialogResult enumeration. The idea is that the text labels are descriptive and make life easier for the developer, while the system uses the underlying numeric values for speed and efficiency. Enumerations are better than either String or Integer when you want to limit the possible choices a variable can take.

I say that the text labels are friendly to the developer, but what about the user? The text labels used for enumerated constants must obey the same rules as other identifiers. That means that they must start with a letter or an underscore and can only contain letters, numbers and underscores. They cannot contain spaces or punctuation. That makes them a little less friendly to display to the user in the UI. It would be nice if we could associate a standard String with each value and display those to the user. Well, we can do that, using the DescriptionAttribute class:

Imports System.ComponentModel
 
Public Enum TestEnum
    <Description("This is the first value")> FirstValue
    <Description("Hello from the second value")> SecondValue
    <Description("Third value here")> ThirdValue
End Enum

Note the spaces in the descriptions that are not allowed in the value names themselves. Now, the question is, how do we actually get those descriptions in code? The answer is to use reflection. In other places I've seen this done with a method at the form level or the like. I've been a good little OOPer and created a couple of classes to do the job. The following EnumDescriptor class encapsulates the reflection code, providing access to an enumerated value and its description via properties:

Imports System.ComponentModel
Imports System.Reflection
 
''' <summary>
''' Contains an enumerated constant value and a friendly description of that value, if one exists.
''' </summary>
''' <typeparam name="T">
''' The enumerated type of the value.
''' </typeparam>
Public Class EnumDescriptor(Of T)
 
    ''' <summary>
    ''' The friendly description of the value.
    ''' </summary>
    Private _description As String
    ''' <summary>
    ''' The enumerated constant value.
    ''' </summary>
    Private _value As T
 
    ''' <summary>
    ''' Gets the friendly description of the value.
    ''' </summary>
    ''' <value>
    ''' A <b>String</b> containing the value's Description attribute value if one exists; otherwise, the value name.
    ''' </value>
    Public ReadOnly Property Description() As String
        Get
            Return Me._description
        End Get
    End Property
 
    ''' <summary>
    ''' Gets the enumerated constant value.
    ''' </summary>
    ''' <value>
    ''' An enumerated constant of the <b>EnumDescriptor's</b> generic parameter type.
    ''' </value>
    Public ReadOnly Property Value() As T
        Get
            Return Me._value
        End Get
    End Property
 
    ''' <summary>
    ''' Creates a new instance of the <b>EnumDescriptor</b> class.
    ''' </summary>
    ''' <param name="value">
    ''' The value to provide a description for.
    ''' </param>
    Public Sub New(ByVal value As T)
        Me._value = value
 
        'Get the Description attribute.
        Dim field As FieldInfo = value.GetType().GetField(value.ToString())
        Dim attributes As DescriptionAttribute() = DirectCast(field.GetCustomAttributes(GetType(DescriptionAttribute), _
                                                                                        False),  _
                                                              DescriptionAttribute())
 
        'Use the Description attribte if one exists, otherwise use the value itself as the description.
        Me._description = If(attributes.Length = 0, _
                             value.ToString(), _
                             attributes(0).Description)
    End Sub
 
    ''' <summary>
    ''' Overridden.  Creates a string representation of the object.
    ''' </summary>
    ''' <returns>
    ''' The friendly description of the value.
    ''' </returns>
    Public Overrides Function ToString() As String
        Return Me.Description
    End Function
 
End Class

I've also created a class to automatically create an EnumDescriptor for each member of an enumeration and store them as a collection:

''' <summary>
''' A collection of EnumDescriptors for an enumerated type.
''' </summary>
''' <typeparam name="T">
''' The type of the enumeration for which the EnumDescriptors are created.
''' </typeparam>
Public Class EnumDescriptorCollection(Of T)
    Inherits ObjectModel.Collection(Of EnumDescriptor(Of T))
 
    ''' <summary>
    ''' Creates a new instance of the <b>EnumDescriptorCollection</b> class.
    ''' </summary>
    Public Sub New()
        'Populate the collection with an EnumDescriptor for each enumerated value.
        For Each value As T In [Enum].GetValues(GetType(T))
            Me.Items.Add(New EnumDescriptor(Of T)(value))
        Next
    End Sub
 
End Class

An example of how you might use these classes is:

Public Class Form1
 
    Private Sub Form1_Load(ByVal sender As Object, _
                           ByVal e As EventArgs) Handles MyBase.Load
        Me.ComboBox1.DisplayMember = "Description"
        Me.ComboBox1.ValueMember = "Value"
        Me.ComboBox1.DataSource = New EnumDescriptorCollection(Of TestEnum)
    End Sub
 
    Private Sub ComboBox1_SelectedIndexChanged(ByVal sender As Object, _
                                               ByVal e As EventArgs) Handles ComboBox1.SelectedIndexChanged
        MessageBox.Show(Me.ComboBox1.SelectedValue.ToString(), Me.ComboBox1.Text)
    End Sub
 
End Class

So, there's no need for you to mess around each time you want to do this once you have these classes. It's one line to create a collection containing the enumerated values and their descriptions, which you can bind or use however you like.

I've attached code files for the EnumDescriptor and EnumDescriptorCollection classes.