History lesson: Anders was lured away from Borland by Microsoft with a hefty offer of a $1.5 million signing bonus, a base salary of up to $200,000, and options to buy 75,000 shares of Microsoft stock.

Looks like it was worth it, as each C# release has added many interesting and powerful features, while maintaining a fine balance between complexity and simplicity.

GetName

Why does GetName return null for any integral type you pass it except those that correspond to a constant?

For example, this is completely valid:

enum Fruit : byte { Apple, Orange, Cumquat };
var fruit = Enum.GetName( typeof(Fruit), ulong.MaxValue );
// fruit now equals null

In every other case in the Enum class where you pass an integral value outside the range of the underlying type, you get an exception. Except here.

IsDefined

Why does IsDefined throw an exception when you pass it an integral value that can be safely narrowed to the enumeration’s underlying type?

For example, this will throw an exception:

enum Fruit : byte { Apple, Orange, Cumquat };
var defined = Enum.IsDefined( typeof(Fruit), 0 );

Why? Because it’s a integer literal (and therefore type int) and the underlying type of Fruit is byte. This would be alright if this is how the Enum class consistently treated this case, but it’s not. In every other method, the Enum class is OK with you passing in an int value for a byte enumeration (as long as it’s within the range of the underlying type).

ToObject

Why does ToObject silently overflow for values outside the range of the enumeration’s underlying type?

For example, this code will give the following non-intuitive result:

enum Fruit : byte { Apple, Orange, Cumquat };
var apple = Enum.ToObject( typeof(Fruit), 0 );
var elppa = Enum.ToObject( typeof(Fruit), 256 );
Assert.AreEqual(apple, elppa);

Assuming that we ignore the fact that silently overflowing is typically a bad idea, this is again completely inconsistent with the rest of the library. Why overflow here, but not in GetName?

Conclusion

The .NET Enum class is not lacking in it’s ability to extract any information you need from an enumeration. It is, however, a little inconsistent in terms of how it treats underlying type mismatches, overflows and narrowing conversions. Barring a new, generified Enum class from Microsoft, the best way to deal with these inconsistencies is to either be aware of them, or use a third-party library to hide them.

(Edit: Some people have noted that my conclusion was a bit weak and preachy towards Dnum, which I have to admit is not without truth. I’ve seen edited it. For the record, the old conclusion was: “Fortunately, these and other problems have been fixed in my Dnum library, which should be released in the next couple days. Be sure to check it out.”).

That works all fine and dandy, as long as the strings you want to store in the database are valid C# identifiers.

What do I mean? Well, consider an enum of something like shipping countries. Imagine we’re only shipping to Canada and the USA. That’s easy enough:

// Country.cs
public enum Country
{
  Canada,
  USA
}

Now imagine that after we write that code, we find out the customer hates TLAs and wants the database entry to contain “United States of America”. When we go to the enum to change it, we realize we’re screwed. You can’t have spaces in a C# identifier!

// Country.cs
public enum Country
{
  Canada,
  United States of America // Compile error!
}

Fortunately, the ever-flexible NHibernate can handle this case using the procedure outlined here.

Let’s apply this procedure to the shipping locations example. Recall that C# was not happy with us putting spaces in our enum members. How can we make that code compile? Well, an underscore is a valid part of a C# identifier, and it’s kinda like a space, so let’s try that:

// Country.cs
public enum Country
{
  Canada,
  United_States_of_America // C# is happy!
}

Next, we need to derive our EnumStringType class so that NHibernate will store the string value of the enum instead of the integer value:

// CountryEnumStringType.cs
class CountryEnumStringType : NHibernate.Type.EnumStringType
{
  // The 30 is the size of the field in the DB.
  public CountryEnumStringType()
      : base(typeof (Country), 30)
  {
  }
  ...
}

Cool, cool, so far so good. This is about how much we’d need to do if we had no spaces to worry about. Unfortunately, if we used these two classes we made as is, the database would contain “United_States_of_America” instead of “United States of America”. And that’s no good… so how do we get around that?

Why, we need to override the GetValue and GetInstance methods, of course!

Let’s plunk open the NHibernate source code and see what they have there now, to use as a guide. Ahh, there she is:

///
///
///
///
 
///
public virtual object GetInstance(object code)
{
  //code is an named constants defined for the enumeration.
  try
  {
    return StringToObject(code as string);
  }
  catch (ArgumentException ae)
  {
    throw new HibernateException(
      string.Format("Can't Parse {0} as {1}",
      code, ReturnedClass.Name), ae);
  }
}
 
///
///
///
///
 
///
public virtual object GetValue(object code)
{
  //code is an enum instance.
  return code == null ? string.Empty : code.ToString();
}

The comments aren’t the greatest, but we can figure out what’s going on. GetInstance converts a string in an enum instance, and GetValue converts an enum to a string.

With that in mind, let’s get to work. First, let’s put in some stubs in our CountryEnumStringType class:

// CountryEnumStringType.cs
class CountryEnumStringType : NHibernate.Type.EnumStringType
{
  // The 30 is the size of the field in the DB.
  public CountryEnumStringType()
      : base(typeof (Location), 30)
  {
  }
 
  ///
  /// Converts a string to an enum instance.
  ///
  public override object GetInstance(object code)
  {
 
  }
 
  ///
  /// Converts a enum instance to a string.
  ///
  public override object GetValue(object code)
  {
 
  }
}

Sweet. Now, our basic strategy here is this:

• when NHibernate asks for an enum instance (and passes a string), we want to replace spaces in the string with underscores, and then find the corresponding enum instance.
• when NHibernate asks for a string (and passes an enum instance), we want to convert the enum to a string, and then replace all underscores with spaces.

First, we modify GetInstance:

///
/// Converts a string to an enum instance.
///
public override object GetInstance(object code)
{
  // This is the string coming from the database, so it will
  // have spaces in it that we need to turn into underscores.
  var str = (string) code;
 
  // If the string is null, just pass it on, no need to replace
  // spaces with underscores.
  if (string.IsNullOrEmpty(str)) return StringToObject(str);
  else return StringToObject(str.Replace(" ", "_"));
}

In case you’re wondering where the hell StringToObject came from, and what it does, I can tell you this:

• It was used in the code for the EnumStringType class,
• its name implies that it’s used to convert a string into an object,
• the context in which it is used supports the previous implication, and
• if you really want to know what it does, read the code for the AbstractEnumType base class.

With that out of the way, let’s move on to writing the code for the GetValue method. In this case we’re looking at converting an enum instance into a string (that will eventually be stored in the database):

///
/// Converts a enum instance to a string.
///
public override object GetValue(object code)
{
  return code == null
    ? string.Empty
    : code.ToString().Replace('_', ' ');
}

The GetValue is pretty straight forward. We basically just tagged on the Replace method to replace all underscores with spaces.

That should about do it. To close, I’ll give a sample usage of it:

// Order.cs
public class Order
{
  public virtual long Id { get; set; }
  ...
  public virtual Country Country { get; set; }
  ...
}

Then this would be the mapping:

<!-- Order.hbm.xml -->
<class name="Order" table="TblOrder">
  ...
  <property name="Country"
    type="WebApp.Domain.CountryEnumStringType, WebApp" />
  ...
</class>

Recently, I’ve started a fairly large project in C# 3.0. As it happens, there came a point where I wanted to use a pattern similar to Bloch’s Builder. However, as anyone who tries to use this pattern in C# will quickly find out, Bloch’s Builder doesn’t translate perfectly to C#.

Here is how Bloch’s Builder looks in C# (with changes made only for syntax):

public class NutritionFacts
{
  public int ServingSize { get; private set; }
  public int Servings { get; private set; }
  public int Calories { get; private set; }
  ...
 
  public class Builder
  {
    private int ServingSize { get; set; }
    private int Servings { get; set; }
    private int Calories { get; set; }
 
    public Builder(int servingSize, int servings)
    {
      ServingSize = servingSize;
      Servings = servings;
    }
 
    public Builder Calories(int calories)
    { Calories = calories; return this; }
    ...
 
    public NutritionFacts Build()
    {
      return new NutritionFacts(this);
    }
  }
 
  private NuitritionFacts(Builder builder)
  {
    ServingSize = builder.ServingSize;
    Servings = builder.Servings;
    Calories = builder.Calories;
    ...
  }
}

If you try to compile that code, the C# compiler will complain, saying that it does not have permission to access the private members of the Builder class.

Then how come it worked in Java? The answer is that Java has a special rule that allows Java outer classes to access the private members of their inner classes. In C#, this rule does not exist, and thus C# outer classes cannot access the private members of C# inner classes.

Since Bloch’s Builder pattern doesn’t work in C#, the natural next question is: how do we make it work?

Approach 1: Make Builder Properties Public

The C# compiler tells us that it can’t compile because it doesn’t have permission to access private members of the nested Builder class. Thus, the most obvious solution to this is to make them public:

public class NutritionFacts
{ 
  ...
  public class Builder
  {
    public int ServingSize { get; set; }
    public int Servings { get; set; }
    public int Calories { get; set; }      
    ...
  }
  ...
}

This allows the code to compile, and we can use the Builder just as we used it in Java.

However there is one niggling concern: the C# Builder exposes getters in the Builder object. In the Java Builder, when we were constructing an object, we were only able to use methods that contributed to building the object. That is, the Java Builder doesn’t expose any getters. However, in the C# version, our API is polluted by unneeded getters. Let’s see if we can do better.

Approach 2: Build the object in the Builder

As we’ve already seen, C# does not permit outer classes to access the private members of inner classes. However, C# does let us access outer classes from inner classes. Since that’s the case, why don’t we invert the building procedure. That is, let’s build the object in the Builder, instead of in the class being built:

public class NutritionFacts
{
  public int ServingSize { get; private set; }
  public int Servings { get; private set; }
  public int Calories { get; private set; }
  ...
 
  public class Builder
  {    
    private int ServingSize { get; set; }
    private int Servings { get; set; }
    private int Calories { get; set; }
 
    public Builder(int servingSize, int servings)
    {
      ServingSize = servingSize;
      Servings = servings;
    }
 
    public Builder Calories(int calories)
    { Calories = calories; return this; }
    ...    
 
    public NutritionFacts Build()
    {
      return new NutritionFacts
      {
        ServingSize = ServingSize,
        Servings = Servings,
        Calories = Calories,
        ...       
      };
    }
  }
 
  private NuitritionFacts()
  { 
    // Intentionally empty.
  }
}

That, to me, is the closest you can get to the Java pattern. From an API consumer’s point of view, it’ll look identical to a Java Builder.

Alternative Form

There is another alternative to the two C# Builders mentioned earlier in this article. As it stands, Bloch’s Builder can be used as a sort of prototype factory. You can configure the builder and then pump out instances of the class that have that configuration. However, if you’re using the Builder to make a single, immutable instance, a more efficient way would be to avoid copying the data first to the Builder and then to the new instance.

Here’s a version of the Builder (by Jon Skeet) that can be used only once, but avoids unnecessary data copying.

public class NutritionFacts
{
  public int ServingSize { get; private set; }
  public int Servings { get; private set; }
  public int Calories { get; private set; }
  ...
 
  public class Builder
  {       
    private NutritionFacts _facts = new NutritionFacts();
 
    public Builder(int servingSize, int servings)
    {
      _facts.ServingSize = servingSize;
      _facts.Servings = servings;
    }
 
    public Builder Calories(int calories)
    { _facts.Calories = calories; return this; }
    ...    
 
    public NutritionFacts Build()
    {
      var ret = facts;
 
      // Invalidates builder to maintain mutability.
      facts = null;
 
      return ret;
    }
  }
 
  private NuitritionFacts()
  { 
    // Intentionally empty.
  }
}

Some of the advantages of this pattern are:

• No data copying is required at build time. In other words, while you’re setting the properties, you’re doing so on the real object – you just can’t see it yet. This is similar to what StringBuilder does.
• The builder becomes invalid after calling Build() to guarantee immutability. This unfortunately means it can’t be used as a sort of “prototype” in the way that Bloch’s version can.

Conclusion

In this article we’ve looked at 3 different working C# implementations of Bloch’s Builder pattern. The first approach was a quick and dirty fix that got the job done. The second approach applied a bit more finesse and managed to keep the same API as the Java Builder. The final approach was more of a variation on the second approach, offering a more efficient implementation of the pattern if you’re not using the Builder as an object prototype factory.