Deborah's Developer MindScape : CSharp, Enum

Enum.TryParse

Deborah Kurata — Tue, 10 Aug 2010 06:36:24 GMT

If you work with Enum values, you may often need to convert between the Enum, an integer representation of the Enum (to store in a table for example), and the string representation of the Enum (to display to the user for example). .NET 4.0 makes this easier with the new TryParse method.

This example uses a CustomerTypeOption Enum value.

In C#:

public enum CustomerTypeOption
{
    /// <summary>
    /// Customer type is unknown
    /// </summary>
    Unknown = 0,

    /// <summary>
    /// Customer is an individual
    /// </summary>
    Individual = 1,

    /// <summary>
    /// Customer is a corporation
    /// </summary>
    Corporation = 2,

    /// <summary>
    /// Customer is an educational institution
    /// </summary>
    Education = 3,

    /// <summary>
    /// Customer is a government agency.
    /// </summary>
    Government = 4
}

In VB:

Public Enum CustomerTypeOption
    ''' <summary>
    ''' Customer type is unknown
    ''' </summary>
    Unknown = 0

    ''' <summary>
    ''' Customer is an individual
    ''' </summary>
    Individual = 1

    ''' <summary>
    ''' Customer is a corporation
    ''' </summary>
    Corporation = 2

    ''' <summary>
    ''' Customer is an educational institution
    ''' </summary>
    Education = 3

    ''' <summary>
    ''' Customer is a government agency.
    ''' </summary>
    Government = 4
End Enum

The Enum defines the valid types of customers supported in an application.

The TryParse method takes either the integer value (converted to a string) OR the string value and converts it to the Enum type as shown below.

In C#:

int i = 1;
string value = i.ToString();
CustomerTypeOption customerType;
if (Enum.TryParse(value, out customerType))
{ /* Success */ }
else
{ /* Failure */ }

value = "individual";
if (Enum.TryParse(value, true, out customerType))
{ /* Success */ }
else
{ /* Failure */ }

In VB:

Dim i As Integer = 1
Dim value As String = i.ToString()
Dim customerType As CustomerTypeOption
If ([Enum].TryParse(value, customerType)) Then
' Success */
Else
' Failure
End If

value = "individual"
If ([Enum].TryParse(value, True, customerType)) Then
' Success
Else
' Failure
End If

In the first example, the integer 1 is converted to a string and passed as the first parameter to the TryParse method. A variable of the desired Enum type is passed in as the second parameter and is defined as an output parameter (using the out keyword in C#).

If the TryParse succeeds, the method returns true and the converted value is returned in the output parameter. If the method fails, it returns false.

In the second example, the string "individual" is passed as the first parameter. The second parameter is set to true, telling the TryParse method to ignore the case of the first parameter. This allows "individual" to match "Individual" even if the casing is different. The third parameter is then the output parameter.

Use TryParse any time you need to convert from an integer value or string representation to an Enum value.

Enjoy!

Silverlight and RIA: Enum Properties

Deborah Kurata — Tue, 10 Nov 2009 20:58:58 GMT

I mentioned in this prior post that RIA Services did not know how to handle properties that have an Enum data type. The problem is not really that RIA Services does not know how to handle the properties; rather it does not have any knowledge of the Enum itself.

Take this example.

In C#:

public enum CustomerTypeOption
{
    Consumer,
    Corporation,
    Education,
    Government
}

private CustomerTypeOption _CustomerType;
public CustomerTypeOption CustomerType {
get { return _CustomerType; }
set { _CustomerType = value; }
}

In VB:

Public Enum CustomerTypeOption
    Consumer
    Corporation
    Education
    Government
End Enum

Private _CustomerType As CustomerTypeOption
Public Property CustomerType() As CustomerTypeOption
    Get
        Return _CustomerType
    End Get
    Set(ByVal value As CustomerTypeOption)
        _CustomerType = value
    End Set
End Property

This code resides in a Customer class like the one shown in this prior post. If you create a CustomerService domain services class, Silverlight will generate a proxy class containing all of the Customer class properties. However, the generated code contains a syntax error because it does not understand the CustomerTypeOption type.

This problem can be solved by sharing the Enum with Silverlight following the technique detailed in this prior post and shown below.

Let's go through the steps in detail:

1. Add a new file to your business object component and call it Customer.shared.vb (if your component is VB.NET) or Customer.shared.cs (if you are using C#).

2. Add the partial keyword to the class name in the file as shown in the code below.

3. Cut the Enum definition from the Customer class and paste it into this partial class.

In C#:

public partial class Customer
{
    public enum CustomerTypeOption
    {
        Consumer,
        Corporation,
        Education,
        Government
    }
}

In VB:

Partial Public Class Customer

    Public Enum CustomerTypeOption
        Consumer
        Corporation
        Education
        Government
    End Enum

End Class

4. Right click on the Web project linked to your Silverlight project and select Add | Existing Item.

5. In the Add Existing Item dialog, select the file and select Add As Link from the Add button drop down menu.

This links the file between your business object class library project and the Web project linked to your Silverlight project.

6. Build the solution.

Silverlight should now have a copy of the Customer.shared.vb or Customer.shared.cs file under the Generated_Code node. Since the Enum is now defined in the Silverlight project, your CustomerType property in the generated code should compile without errors.

Use this technique any time you want to share an Enum between your business object class library project and your Silverlight project.

Enjoy!

Building a Business Object Base Class

Deborah Kurata — Tue, 21 Jul 2009 18:49:48 GMT

If you are building applications in .NET to manage data for a business, you are most likely creating business object classes. Depending on the business, these classes could include Customer, Product, Order, Invoice, PurchaseOrder, Employee, TimeCard and so on.

A simple sample Customer class is shown here.

There are some features that all business objects need to support. For example:

Entity State: The business object needs to track whether it is new, updated, or deleted so it can make the appropriate change to the database.
Validation: Is the current data defined for the business object valid?
Save: Saves the changes to the database.

Notice that data retrieval functionality is not included in this list. That is because in most cases, you may never retrieve a single business object. Rather, you would retrieve a set of them. For example, all active orders or all customers with overdue invoices. So the retrieve functionality is not included in the class that manages a single object. (Most on this in a later post.)

Instead of repeating this common functionality in each business object, it makes sense to build a base class. Each business object can then inherit from this base class to share this common functionality.

So let’s get started.

In C#:

using System;
using System.ComponentModel;

public abstract class BoBase :
IDataErrorInfo,
INotifyPropertyChanged
{

}

In VB:

Imports System.ComponentModel

Public MustInherit Class BOBase
Implements IDataErrorInfo
Implements INotifyPropertyChanged

End Class

The class is abstract (MustInherit in VB) to indicate that it is meant to be a base class and not to be used on its own. An abstract class cannot be instantiated directly, so no other code can create an instance of the class.

The class then implements two interfaces:

IDataErrorInfo: This interface provides error information that the user interface can use to report validation errors to the user. It works well with the ErrorProvider control provided in WinForms and supports ASP.NET and WPF features.
INotifyPropertyChanged: This interface ensures that the user interface is notified when a property value changes, keeping your business object and user interface in sync.

We’ll look at the implementation of these interfaces shortly.

First, define the valid set of entity states.

In C#:

protected internal enum EntityStateType
{
    Unchanged,
    Added,
    Deleted,
    Modified
}

In VB:

Protected Friend Enum EntityStateType
    Unchanged
    Added
    Deleted
    Modified
End Enum

The Enum is declared Protected because the entity state should only be accessible from the business object itself. However, Internal (Friend in VB) was added so that related objects (such as Order and OrderLineItem) could reference the related object state.

The business object state is retained using an EntityState property.

In C#:

protected EntityStateType EntityState { get; private set; }

In VB:

Private _EntityState As EntityStateType
Protected Property EntityState() As EntityStateType
    Get
        Return _EntityState
    End Get
    Private Set(ByVal value As EntityStateType)
        _EntityState = value
    End Set
End Property

This property is protected, but the setter is private. So the business objects that inherit from this class can read the entity state, but only the base class can set the value.

Additional properties provide a way to get the entity’s state in an easier fashion. These properties are not required, but they make the base class a little easier to use.

In C#:

[BindableAttribute(false)]
[BrowsableAttribute(false)]
public bool IsDirty
{
get { return this.EntityState != EntityStateType.Unchanged; }
}

[BindableAttribute(false)]
[BrowsableAttribute(false)]
public bool IsNew
{
get { return this.EntityState == EntityStateType.Added; }
}

In VB:

<BindableAttribute(False)> _
<BrowsableAttribute(False)> _
Public ReadOnly Property IsDirty() As Boolean
    Get
        Return Me.EntityState <> EntityStateType.Unchanged
    End Get
End Property

<BindableAttribute(False)> _
<BrowsableAttribute(False)> _
Public ReadOnly Property IsNew() As Boolean
    Get
        Return Me.EntityState = EntityStateType.Added
    End Get
End Property

The IsDirty and IsNew properties are public, so they can be accessed from anywhere. They are marked with two attributes:

Bindable: Defines whether the property should be used for binding. In this case the value is false because the user interface should not be able to bind to this property.
Browsable: Defines whether the property should be displayed in the Properties window. Again, the value is false.

Two other properties handle the validation.

In C#:

[BindableAttribute(false)]
[BrowsableAttribute(false)]
public bool IsValid
{
get { return (ValidationInstance.Count == 0); }
}

protected Validation ValidationInstance { get; set; }

In VB:

<Bindable(False)> _
<BrowsableAttribute(False)> _
Public ReadOnly Property IsValid() As Boolean
    Get
        Return (ValidationInstance.Count = 0)
    End Get
End Property

Private _ValidationInstance As Validation
Protected Property ValidationInstance() As Validation
    Get
        Return _ValidationInstance
    End Get
    Private Set(ByVal value As Validation)
        _ValidationInstance = value
    End Set
End Property

Again, the public property is marked with the Browsable and Bindable attributes. The ValidationInstance property retains an instance of the Validation class for the business object. The code for the Validation class is here.

The constructor creates an instance of the Validation class.

In C#:

protected BoBase()
{
ValidationInstance = new Validation();
}

In VB:

Protected Sub New()
ValidationInstance = New Validation
End Sub

The following is the implementation of IDataErrorInfo.

In C#:

#region IDataErrorInfo Members

[BrowsableAttribute(false)]
[BindableAttribute(false)]
public string Error
{
get { return ValidationInstance.ToString(); }
}

[BrowsableAttribute(false)]
[BindableAttribute(false)]
public string this[string columnName]
{
get { return ValidationInstance[columnName]; }
}

#endregion

In VB:

#Region " Properties required by the IDataErrorInfo"

    <Bindable(False)> _
    <BrowsableAttribute(False)> _
    Public ReadOnly Property [Error]() As String _
           Implements IDataErrorInfo.Error
        Get
            Return ValidationInstance.ToString
        End Get
    End Property

    <BrowsableAttribute(False)> _
    <Bindable(False)> _
    Default Protected ReadOnly Property Item(ByVal columnName _
           As String) As String _
           Implements IDataErrorInfo.Item
        Get
            Return ValidationInstance.Item(columnName)
        End Get
    End Property

#End Region

The Error property uses the overridden ToString method of the validation class to return the full list of validation errors.

The Item property provides access to the validation errors given a property name. This property is implemented as the class indexer in C#.

The following in the implementation of INotifyPropertyChanged.

In C#:

#region INotifyPropertyChanged Members
public event PropertyChangedEventHandler PropertyChanged;
#endregion

In VB:

#Region " Events required by INotifyPropertyChanged"
    Public Event PropertyChanged(ByVal sender As Object, _
        ByVal e As System.ComponentModel.PropertyChangedEventArgs) _
        Implements INotifyPropertyChanged.PropertyChanged
#End Region

This interface only defines a single event. This event should be raised whenever the data is changed.

Since every business object will have unique requirements for the save operation, the SaveItem method is not implemented. Rather it is defined as abstract.

In C#:

public abstract Boolean SaveItem();

In VB:

Public MustOverride Function SaveItem() As Boolean

Defining an abstract (MustOverride in VB) SaveItem method ensures that every business object has a SaveItem method.

Finally, since the EntityState property setter is private, the base class needs a method to set the entity state.

In C#:

protected internal void SetEntityState(EntityStateType newEntityState)
{
    switch (newEntityState)
    {
        case EntityStateType.Deleted:
        case EntityStateType.Unchanged:
        case EntityStateType.Added:

            this.EntityState = newEntityState;
            break;

    default:
            if (this.EntityState == EntityStateType.Unchanged)
                this.EntityState = newEntityState;
            break;
    }
}

protected internal void SetEntityState(EntityStateType newEntityState, string propertyName)
{
    SetEntityState(newEntityState);
    if (PropertyChanged != null)
        PropertyChanged(this,
               new PropertyChangedEventArgs(propertyName));
}

In VB:

Protected Friend Sub SetEntityState(ByVal dataState As EntityStateType)
SetEntityState(dataState, Nothing)
End Sub

Protected Friend Sub SetEntityState( _
ByVal newEntityState As EntityStateType, ByVal propertyName As String)
    Select Case newEntityState
        Case EntityStateType.Deleted, _
             EntityStateType.Unchanged, _
             EntityStateType.Added

            Me.EntityState = newEntityState

        Case Else
            If Me.EntityState = EntityStateType.Unchanged Then
                Me.EntityState = newEntityState
            End If
    End Select

    If Not String.IsNullOrEmpty(propertyName) Then
        Dim e As New PropertyChangedEventArgs(propertyName)
        RaiseEvent PropertyChanged(Me, e)
    End If
End Sub

The SetEntityState method has two overloads. The first is used when changing the entity state in general and the second is used when changing the entity state because a specific property is changed.

For example, when setting an object as Unchanged, Added, or Deleted, it does not matter which property was changed. But when a particular property is changed, the code must also raise the PropertyChanged event.

In this case, the C# and VB code was implemented differently. In the C# code, the code to set the entity state is in the first overload. The second overload then calls the first and then raises the event.

In the VB code, the first overload simply calls the second overload. The second overload then sets the entity state and then raises the event as appropriate. You can use either technique in either language.

That’s it! You now have a base class that can be used with any business object class. If you have any other common functionality, you can add it to this base class.

Here is an example of how you use this base class.

In C#:

public class Customer : BoBase
{

    private string _LastName;
    public string LastName
    {
        get { return _LastName; }
        set
        {
            if (_LastName == null || _LastName != value)
            {
              string propertyName = "LastName";
              _LastName = value;

              // Validate the last name
              ValidationInstance.ValidateClear(propertyName);
              ValidationInstance.ValidateRequired(propertyName, value);

              SetEntityState(EntityStateType.Modified, propertyName);
            }
        }
    }

    public override Boolean SaveItem()
    {
        // TODO: Add code here
    }

}

In VB:

Public Class Customer
Inherits BoBase

    Private _LastName As String
    Public Property LastName() As String
        Get
            Return _LastName
        End Get
        Set(ByVal value As String)
            If _LastName Is Nothing OrElse _LastName <> value Then
              Dim propertyName As String = "LastName"
              _LastName = value

              ' Validate the last name
              ValidationInstance.ValidateClear(propertyName)
              ValidationInstance.ValidateRequired(propertyName, value)

              SetEntityState(EntityStateType.Modified, propertyName)
            End If
        End Set
    End Property

    Public Overrides Function SaveItem() As Boolean
        ' TODO: Add code here
    End Function
End Class

Notice how the class statement includes the syntax to inherit from BoBase. The LastName property uses the ValidationInstance defined in the base class to validate the value. It also sets the entity state when the last name is changed.

Enjoy!

Enum: Binding to the Description Attribute

Deborah Kurata — Fri, 10 Jul 2009 23:31:04 GMT

The Enum keyword allows you to define a standard set of named constants for use in your application. Sometimes you may want to present this same list of values to your user.

You can display the set of Enum values in a ComboBox or ListBox using data binding. And even better, if you use the DescriptionAttribute in the Enum, you can display a more user-friendly set of values.

For example, a Customer business object may have a CustomerType defined with a specific set of options for corporations, individuals, schools, and charities. You want to use these values in your code, but also display them to the user in a ComboBox.

Enum Definition

The Enum can reside in the Customer class, or in its own class.

In C#:

public enum CustomerTypeOption
{
    NotDefined,
    Corp,
    IndividualorFamily,
    SchoolorUniversity,
    Charity
}

In VB:

Public Enum CustomerTypeOption
   NotDefined
   Corp
   IndividualorFamily
   SchoolorUniversity
   Charity
End Enum

CustomerType Property

A CustomerType property in the Customer class can use this enum type.

In C#:

public CustomerTypeOption CustomerType { get; set; }

In VB:

The C# code uses the automatically implemented properties feature introduced with .NET 3.5. The VB code uses the full property definition.

Binding To an Enum

The Enum can also be used by the user interface. For example, you can bind a comboBox or listBox to a set of customer type options.

In C#:

Dictionary<string, int> CustomerTypeList =
                           new Dictionary<string, int>();

foreach (int enumValue in
             Enum.GetValues(typeof(Customer.CustomerTypeOption)))
{
    CustomerTypeList.Add(
         Enum.GetName(typeof(Customer.CustomerTypeOption),
                                      enumValue ), enumValue);
}

// Bind the customer type combo box
CustomerTypeComboBox.DisplayMember = "Key";
CustomerTypeComboBox.ValueMember = "Value";
CustomerTypeComboBox.DataSource = new BindingSource(CustomerTypeList,
null);

In VB:

Dim CustomerTypeList As New Dictionary(Of String, Integer)

For Each enumValue As Integer In _
            [Enum].GetValues(GetType(Customer.CustomerTypeOption))
    CustomerTypeList.Add( _
       [Enum].GetName(GetType(Customer.CustomerTypeOption), _
                                        enumValue), enumValue)
Next

' Bind the combo box
CustomerTypeComboBox.DisplayMember = "Key"
CustomerTypeComboBox.ValueMember = "Value"
CustomerTypeComboBox.DataSource = New BindingSource(CustomerTypeList, _
Nothing)

This code defines a Dictionary to contain the name of the enum and the integer value of the enum. The for/each loop iterates through the set of Enum values and adds the name and value to the dictionary.

The code then binds to the ComboBox, setting the DisplayMember to the “Key” of the dictionary and the ValueMember to the “Value” of the Dictionary.

The result looks like this:

While it does provide the appropriate options, it is not very user-friendly. It would be nicer if there were appropriate spaces and full words. For that, you can use the DescriptionAttribute on the Enum.

Using the DescriptionAttribute

NOTE: Be sure to import the System.ComponentModel and the System.Reflection namespaces.

In C#:

public enum CustomerTypeOption
{
[DescriptionAttribute("Not Specified")]
NotDefined,

[DescriptionAttribute("Corporation")]
Corp,

[DescriptionAttribute("Individual or Family")]
IndividualorFamily,

[DescriptionAttribute("School or University")]
SchoolorUniversity,

[DescriptionAttribute("Charity")]
Charity
}

In VB:

Public Enum CustomerType
<DescriptionAttribute("Corporate Customer")> _
CorpCustomer

<DescriptionAttribute("Individual or Family")> _
IndividualorFamily

<DescriptionAttribute("School or University")> _
SchoolorUniversity

<DescriptionAttribute("Charity")> _
Charity

<DescriptionAttribute("Kingdom")> _
Kingdom
End Enum

Binding to an Enum Description

Now you can bind to the description instead of to the Enum constant.

In C#:

Dictionary<string, int> CustomerTypeList =
new Dictionary<string, int>();

FieldInfo fi;
DescriptionAttribute da;
foreach (Customer.CustomerTypeOption enumValue in
           Enum.GetValues(typeof(Customer.CustomerTypeOption)))
{
    fi = typeof(Customer.CustomerTypeOption).
                    GetField((enumValue.ToString()));
    da = (DescriptionAttribute)Attribute.GetCustomAttribute(fi,
                    typeof(DescriptionAttribute));
    if (da != null)
    {
       CustomerTypeList.Add(da.Description, (int)enumValue);
    }
}

In VB:

Dim CustomerTypeList As New Dictionary(Of String, Integer)

Dim fi As FieldInfo
Dim da As DescriptionAttribute
For Each enumValue As Customer.CustomerTypeOption In _
            [Enum].GetValues(GetType(Customer.CustomerTypeOption))
    fi = GetType(Customer.CustomerTypeOption). _
                GetField(enumValue.ToString)
    da = DirectCast(Attribute.GetCustomAttribute(fi, _
                GetType(DescriptionAttribute)), DescriptionAttribute)
    If da IsNot Nothing Then
        CustomerTypeList.Add(da.Description, enumValue)
    End If
Next

' Bind the combo box
CustomerTypeComboBox.DisplayMember = "Key"
CustomerTypeComboBox.ValueMember = "Value"
CustomerTypeComboBox.DataSource = New BindingSource(CustomerTypeList, _
Nothing)

This code defines a Dictionary to contain the description of the enum and the integer value of the enum. The for/each loop iterates through the set of Enum values. It uses reflection to find the DescriptionAttribute. It then adds the description and value to the dictionary.

The code then binds to the ComboBox, setting the DisplayMember to the “Key” of the dictionary and the ValueMember to the “Value” of the Dictionary.

Now the combo box looks like this:

Much better!

Extension Methods

So the user interface looks nicer, but the code to get the DescriptionAttribute looks rather tedious. It would be much nicer if there was a GetDescription method on the Enum. But hey, with the extension method feature introduced in .NET 3.5, we can build one ourselves!

In C#:

public static string GetDescription(this Enum currentEnum)
{
string description = String.Empty;
DescriptionAttribute da ;

    FieldInfo fi = currentEnum.GetType().
                GetField(currentEnum.ToString());
    da = (DescriptionAttribute)Attribute.GetCustomAttribute(fi,
                typeof(DescriptionAttribute));
    if (da != null)
        description = da.Description;
    else
        description = currentEnum.ToString();

return description;
}

In VB:

<ExtensionAttribute()> _
Public Function GetDescription(ByVal currentEnum As [Enum]) As String
Dim description As String = String.Empty
Dim da As DescriptionAttribute

    Dim fi As FieldInfo = currentEnum.GetType. _
                GetField(currentEnum.ToString)
    da = DirectCast(Attribute.GetCustomAttribute(fi, _
                GetType(DescriptionAttribute)), DescriptionAttribute)
    If da IsNot Nothing Then
        description = da.Description
    Else
        description = currentEnum.ToString
    End If

Return description
End Function

The C# code can reside in any static class. The VB code must reside in a module, which provides the same features as a static class.

This code uses reflection to get the DescriptionAttribute for any Enum value. So it can be readily reused. The code returns the DescriptionAttribute if one is found, otherwise it returns the name.

Binding to an Enum Description - Redux

Now the binding code is much easier to work with.

In C#:

Dictionary<string, int> CustomerTypeList =
new Dictionary<string, int>();

foreach (Customer.CustomerTypeOption enumValue in
Enum.GetValues(typeof(Customer.CustomerTypeOption)))
{
CustomerTypeList.Add(enumValue.GetDescription(), (int)enumValue);
}

In VB:

Dim CustomerTypeList As New Dictionary(Of String, Integer)

For Each enumValue As Customer.CustomerTypeOption In _
[Enum].GetValues(GetType(Customer.CustomerTypeOption))
CustomerTypeList.Add(enumValue.GetDescription, enumValue)
Next

' Bind the combo box
CustomerTypeComboBox.DisplayMember = "Key"
CustomerTypeComboBox.ValueMember = "Value"
CustomerTypeComboBox.DataSource = New BindingSource(CustomerTypeList, _
Nothing)

Enjoy!