.NET 1.1+

Adding Descriptive Text to Enumerations

by Richard Carr, published at http://www.blackwasp.co.uk/EnumDescription.aspx

Enumerations allow a number of constants to be declared in a group. These constants provide names for numeric values to make code easier to read and maintain. The names are not ideally formatted for display to users but can be enhanced with descriptions.

Enumerations

C# allows constants and enumerations to be declared. Constants allow names to be assigned to fixed values of varying types. An enumeration defines a number of related constants for numeric values, each with a unique name. This can enhance the readability of code, as the names of constants can be self-documenting. However, as the names of enumeration values must conform to the standards for C# identifiers, they are not always suitable for output. This is most obvious when working with constants that combine two or more words, as no spaces, punctuation or other special characters are permitted.

The individual constants in an enumeration can be given descriptions that are more appropriate for display to the user. In this article we will create an enumeration that is decorated with Description attributes. We will then create an extension method that uses reflection to obtain a description and return it as a string. If you are using a version of the .NET framework that does not support extension methods, you can convert use a standard static method instead.

Description Attribute

The Description attribute can be applied to each of the constants in an enumeration. It is found in the System.ComponentModel namespace so add the following using directive to simplify the code.

using System.ComponentModel;

We can now create the enumeration using the standard syntax. The user-friendly text for each value is provided to the only parameter of the Description attribute. Add the following code to your test project. The values define several basic colours and some descriptive names that may be used by a car manufacturer. Note that the last value, "Red", does not have a description. This will allow us to test that the method works with items that do not have the attribute.

enum CarColour
{
    [Description("Ice Cream White")]
    White,

    [Description("Carbon Black")]
    Black,

    [Description("Sterling Silver")]
    Silver,

    Red
}

Creating the Extension Method

The extension method will use reflection to examine the values in any enumeration and look for the Description attribute. Where present, the description will be returned. If the description is absent, the constant name will be returned instead. To simplify the code that uses reflection, add the following using directive:

using System.Reflection;

We can now create the method, as follows:

public static class EnumExtensions
{
    public static string Description(this Enum enumValue)
    {
        var enumType = enumValue.GetType();
        var field = enumType.GetField(enumValue.ToString());
        var attributes = field.GetCustomAttributes(typeof(DescriptionAttribute), false);
        return attributes.Length == 0
            ? enumValue.ToString()
            : ((DescriptionAttribute)attributes[0]).Description;
    }
}

The method performs several actions. In the first line, the type of the enumeration is obtained. This is necessary as the extension method will work with any enumeration, not just CarColours. Next, the GetField method is called, passing the name of the enumeration value provided in the method's parameter. This obtains the field information for the value.

The third step calls the GetCustomAttributes method of the field information object. As the type of the Description attribute is provided, this call returns any Description attribute defined for the value. The results are returned as an array of objects. The final line checks if any items exist in this array. If the array is empty the ToString method of the value is returned. This gives the name of the constant. If there is a value in the array, it is cast as a DescriptionAttribute and the Description property is returned. This is the text defined in the attribute.

Testing the Extension Method

To test the method we can loop through all of the constants in the enumeration and output the return value of the Description method for each item, as follows. Note that the last item, which has no description, returns the constant name.

for (CarColour cc = CarColour.White; cc <= CarColour.Red; cc++)
{
    Console.WriteLine(cc.Description());
}

/* OUTPUT

Ice Cream White
Carbon Black
Sterling Silver
Red

*/