That’s not to say there aren’t problems. The documentation is definitely a problem, one to which I’ll try to make a small contribution in solving. I intend to post more about WiX in the future, but for now, I’ll cover one small thing which is setting properties for your WiX project in an automated build with MSBuild.

Part of the pretty good Visual Studio support is it’s own MSBuild-based project file. It has custom tasks that wrap the underlying command-line utilities, candle, lit, light, etc. This makes it really easy to make it part of your daily build or CI builds. One thing that often gets taken over by the build process is setting the version number of your assemblies. Versioning is especially important when it comes to installers, so keeping the installer version in sync with the application version is definitely a good practice.

To do this with your WiX installer project, we first have turn the version value to a variable. (Forgive me if I use the incorrect terms here, I don’t know the formal WiX names for these things. I’ll gladly change it if someone corrects me.)

Suppose we have the following, default wxs file given to us by Votive in Visual Studio:

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
    <Product Id="*" 
            Name="WixProject1" 
            Language="1033" 
            Version="1.0.0.0" 
            Manufacturer="WixProject1" 
            UpgradeCode="c93e09b9-9e8f-444c-a35b-84beb2c3788f">
        <Package InstallerVersion="200" Compressed="yes" />

        <Media Id="1" Cabinet="WixProject1.cab" EmbedCab="yes" />

        <Directory Id="TARGETDIR" Name="SourceDir">
            <Directory Id="ProgramFilesFolder">
                <Directory Id="INSTALLLOCATION" Name="WixProject1">
                    <!-- TODO: Remove the comments around this Component element
               and the ComponentRef below in order to add resources to this installer. -->
                    <!-- <Component Id="ProductComponent" Guid="51acaaef-c2fb-4ef3-a641-9475c81ac948"> -->
                        <!-- TODO: Insert files, registry keys, and other resources here. -->
                    <!-- </Component> -->
                </Directory>
            </Directory>
        </Directory>

        <Feature Id="ProductFeature" Title="WixProject1" Level="1">
            <!-- TODO: Remove the comments around this ComponentRef element
         and the Component above in order to add resources to this installer. -->
            <!-- <ComponentRef Id="ProductComponent" /> -->
        </Feature>
    </Product>
</Wix>

The property we’re concerned with is the Version attribute on the Product element. Right now it’s set to 1.0.0.0. The first thing we need to do is change this into a variable so that we can set the value from elsewhere. To do that we change the Version attribute above into the following:

<Product Id="*" 
         Name="WixProject1" 
         Language="1033" 
         Version="$(var.ProductVersion)" 
         Manufacturer="WixProject1" 
         UpgradeCode="c93e09b9-9e8f-444c-a35b-84beb2c3788f">
...
</Product>

This creates a preprocessor variable called ProductVersion (you can call it whatever you want). If you build the installer now, you get an error saying “Error    1    Undefined preprocessor variable ‘$(var.ProductVersion)’. “

Now we have to define that elsewhere. And where else but the project file!

To edit that, right click on the project node in solution explorer, select Unload Project… Then right click again and select Edit <ProjectName>.wixproj. You’ll get the proj file loaded as XML in the editor. Let me draw your attention to one of the PropertyGroups:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">
  <OutputPath>bin\$(Configuration)\</OutputPath>
  <IntermediateOutputPath>obj\$(Configuration)\</IntermediateOutputPath>
  <DefineConstants>Debug</DefineConstants>
</PropertyGroup>

This is a property group that is only defined if the Configuration property is Debug and Platform is x86. You see that DefineConstants property set to Debug? That’s where we want to define our ProductVersion variable, like so:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">
  <OutputPath>bin\$(Configuration)\</OutputPath>
  <IntermediateOutputPath>obj\$(Configuration)\</IntermediateOutputPath>
  <DefineConstants>Debug;ProductVersion=1.0.0.0</DefineConstants>
</PropertyGroup>

In general, you want to define all your properties in Name=Value; format. OK, we have that entered, so close the file, right click on the project node again in SOlution Explorer, select Reload Project. This makes Visual Studio read the project file again. Build again. No errors! Neat, eh?

Now we’ve managed to move setting the of the ProductVersion property into the MSBuild file, but remember what I said about that property group? It’s only defined in Debug builds. If we switched our project to Release, then we’d get the Undefined variable error again. (This is actually a big usability problem in VS, IMO; this happens all the time for many properties and settings).

What we really want is the ProductVersion property defined for all build configurations. But while we’re developing our installer, we want to use Visual Studio, so we don’t have to constantly go into the proj file to change things. No problem, I got you covered.

The good folks developing WiX for all of us obviously have our interests in mind by setting that Debug property by default, so we’re going to want to save that. We also want to define ProductVersion for Release builds. Let’s consider all the PropertyGroups in the wixproj file, the answer is practically shouting at us:

<PropertyGroup>
  <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
  <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
  <ProductVersion>3.0</ProductVersion>
  <ProjectGuid>{9b84d861-ac5d-4559-bc9c-0e59cb95ad90}</ProjectGuid>
  <SchemaVersion>2.0</SchemaVersion>
  <OutputName>WixProject1</OutputName>
  <OutputType>Package</OutputType>
  <WixTargetsPath Condition=" '$(WixTargetsPath)' == '' ">$(MSBuildExtensionsPath)\Microsoft\WiX\v3.0\Wix.targets</WixTargetsPath>
  <Name>WixProject1</Name>     
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">
  <OutputPath>bin\$(Configuration)\</OutputPath>
  <IntermediateOutputPath>obj\$(Configuration)\</IntermediateOutputPath>
  <DefineConstants>Debug;ProductVersion=1.0.0.0</DefineConstants>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x86' ">
  <OutputPath>bin\$(Configuration)\</OutputPath>
  <IntermediateOutputPath>obj\$(Configuration)\</IntermediateOutputPath>
</PropertyGroup>

First thing we should do is add the DefineConstants property with our ProductVersion property in Release:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x86' ">
  <OutputPath>bin\$(Configuration)\</OutputPath>
  <IntermediateOutputPath>obj\$(Configuration)\</IntermediateOutputPath>
  <DefineConstants>ProductVersion=1.0.0.0</DefineConstants>
</PropertyGroup>

Got it, now: check out the Configuration and Platform properties in the first PropertyGroup. See what they do? They define a default if empty. Now why couldn’t we do that? We’ll define another property in the first property group called Version (you can call it what you like):

<Version Condition=" '$(Version)' == '' ">1.0.0.0</Version>

Alright, one more step, we replace the value in our DefineConstants declarations. I’ll do the Debug version, you do the Release:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">
  <OutputPath>bin\$(Configuration)\</OutputPath>
  <IntermediateOutputPath>obj\$(Configuration)\</IntermediateOutputPath>
  <DefineConstants>Debug;ProductVersion=$(Version)</DefineConstants>
</PropertyGroup>

Got the Release section finished? Awesome. Reload the project. Build. Awesome.

It works!

Now, we can build this project on the command line and set any version we want.

msbuild installer.proj /p:Version=3.1.0.0

One thing to note though. Ideally, you’re going to mix and match your product assemblies and product installer. Well, maybe not, but if you have any code-based custom actions, you’re probably going to have a C# or VB project in you product installer solution.

The bad news is that the CSharp.targets file, the file with all the default C# build tasks also defines a DefineConstants property. It’s used for setting DEBUG and TRACE and all those. They conform to a certain format; one that doesn’t include Name=Value; formatting. So you get unnecessary warnings.

I’m not sure why they decided to reuse a well-known property name. Was it really so hard to type <PreprocessorVariable>?

Consider this code:

this.checkBox1.DataBindings.Add("Checked", this.myBindingSource, "MyBooleanProperty",
                                 true, DataSourceUpdateMode.OnPropertyChanged);

This declares a data binding on checkBox1, a CheckBox control. It uses the giant overload taking arguments that, respectively, declare the name of the property on the Control to bind to, the source of the data property, the data property, a boolean for formatting, and a DataSourceUpdateMode enum value.

The DataSourceUpdateMode.OnPropertyChanged value means that as soon as the control’s Checked property changes, then change the MyBooleanProperty on the data source. OnPropertyChanged is not the default; the default is OnValidation which typically happens when the control loses focus. I’m a fan of PropertyChanged because there are problems with OnValidation when focus doesn’t change.

Anyway, if you bind to the Checked property on CheckBox, and select DataSourceUpdateMode.OnPropertyChanged, then it updates on validation.

BZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZT! Wrong! Bug!

Fortunately, there is a workaround. If you use the useless, and practically redundant, CheckState property on CheckBox, instead of Checked, then you get OnPropertyChanged updating. Important: Make sure ‘true’ is passed for the formattingEnabled parameter, otherwise the value expected by the control will be of type CheckState, an enum.

The following code works:

this.checkBox1.DataBindings.Add("CheckState", this.myBindingSource, "MyBooleanProperty", 
                                true, DataSourceUpdateMode.OnPropertyChanged);

Your welcome.

I’m sure, Dear Reader, if you wait long enough, I’ll do all the exercises I leave to you in my posts. I wrote last time about displaying enums in WPF using databinding. I left it as an exercise to do this in Windows Forms and ASP.NET. Well, it turns out that I needed a Windows Forms version for more than just a programming exercise. So I figured I’d share something like it with all 5 of you regular readers.

In case you don’t want to click through to the WPF article, let me recap it here for you since we’ll be using some of the code from that article. I’m ambivalent towards enums; I often think they are less useful in many situations in which they are used than a custom class. I do, however, have little choice when it comes to using other libraries or .NET Framework code which may use them. One of the troublesome areas of enums is showing them in UI without going insane writing the same code over and over again with only the slight difference of the enum type to distinguish each version.  Last time I used the first-rate data-binding in WPF to show enums in a WPF ComboBox. Then I handled the case where you don’t own the enum. I also dealt with the issues of internationalization and human readable text instead of the names of each enum value. In this article, I’ll use the somewhat less first-rate data-binding in Windows Forms to do the same thing.

The first thing we need is a way to mark our enum with the text we want in place of the value name. The perfect way to do that, as I said last time, is to use attributes. The class I presented last time is independent of UI frameworks, so I’ll use it again here. It’s reproduced below:

using System;

namespace MissingNet.ComponentModel
{
   [AttributeUsage(AttributeTargets.Field)]
   public sealed class DisplayStringAttribute : Attribute
   {
      private readonly string value;
      public string Value
      {
         get { return value; }
      }

      public string ResourceKey { get; set; }

      public DisplayStringAttribute(string value)
      {
         this.value = value;
      }

      public DisplayStringAttribute()
      {
      }
   }
}

We can apply this to the values of our custom enum, like so:

public enum MyEnum
{
   [DisplayString("My Value")]
    Value,
   [DisplayString("This means On")]
    On,
   [DisplayString("Off means not On")]
    Off,
   [DisplayString("The great unknown")]
    Unknown,
   [DisplayString("I ain't got none")]
    None
}

Doesn’t look as pretty as an unadorned enum, but commercial quality code often looks less attractive than you’re typical code snippet on MSDN. If we want to internationalize our app, we can have different display strings for different languages by setting the ResourceKey property instead of the value constructor:

public enum MyEnum
{
   [DisplayString(ResourceKey="MyEnum_Value")] Value,
   [DisplayString(ResourceKey="MyEnum_On")] On,
   [DisplayString(ResourceKey="MyEnum_Off")] Off,
   [DisplayString(ResourceKey="MyEnum_Unknown")] Unknown,
   [DisplayString(ResourceKey="MyEnum_None")] None
}

Don’t forget to add the strings to your resx file for each language!

Now that we’ve reviewed how to associate the display strings with the enum values, we need a way to get that data into the UI. For that I’ll be using one of the unsung heroes of the .NET 2.0 WinForms improvements: BindingSource.

Earlier I called the data-binding in WinForms less than first-rate. It’s only in comparison to WPF, which isn’t really fair: WPF was designed from the ground up with data-binding as a feature. By contrast, Windows Forms is an elegant OO wrapper around the flat Win32 API, an API that is ancient in computer years. It’s so old they didn’t even have data when it was designed. So there is nothing as elegant as, say, DataContext in Windows Forms, but it’s still world’s better than the alternative of doing it all yourself.

If Win32 were a Star Wars character: really powerful, but really, really old

They faked it pretty good in .NET 1.1 for simple databinding (simple in the Windows Forms data binding sense of just hooking up to a property); complex databinding (binding to a list or collection or DataSet) was a bit more onerous if you modified the collection independent of the Form that was displaying it. In .NET 2.0, they improved things tremendously by following the old adage: You can at least partially solve any problem in computer science with one more level of indirection. [The full quote, attributed to David Wheeler is, “Any problem in computer science can be solved with another layer of indirection. But that usually will create another problem.”]

And that level of indirection takes the form of the BindingSource. To describe the BindingSource, let me quote directly from the excellent book on the subject of Windows Forms databinding, Data Binding with Windows Forms 2.0, by Brian Noyes:

The BindingSource component solves a number of tricky problems that surfaced with the approach of directly binding data sources to controls in .NET 1.X. It provides a layer of indirection between a data source and bound controls that makes a number of things easier. Additionally, it surfaces important control points and access to the underlying data source in a way that saves you from having to delve into the data-binding mechanisms of a form the way you had to in the past. A binding source also gives you a single API to program against from the form’s perspective, and lets a lot of your form code remain decoupled from the specific data source type. This prevents you from having to adapt your programmatic coding patterns to each different type of data that your application works with… [p111-112]

Sounds perfect for our needs, doesn’t it? Displaying enums, from a Windows Forms data-binding perspective, is actually fairly easy: it’s a read-only data source with read-only items, so there is no need to deal with adding, removing or editing. In fact the only tough part is filling the “list” with the entries. We’ve already done something similar with in WPF.

Here’s the EnumBindingSource class:

public class EnumBindingSource : BindingSource
{
  private readonly object dataSource;
  private readonly PropertyInfo property;

  public EnumBindingSource(object dataSource, string propertyName)
  {
     this.dataSource = dataSource;
     this.property = dataSource.GetType().GetProperty(propertyName);
     Type enumType = property.PropertyType;
     FieldInfo[] fields = enumType.GetFields(BindingFlags.Public | BindingFlags.Static);
     List<NameEnumPair> source = new List<NameEnumPair>(fields.Length);
     foreach (FieldInfo f in fields)
     {
        DisplayStringAttribute[] a = (DisplayStringAttribute[])f.GetCustomAttributes(typeof(DisplayStringAttribute), false);
        string displayString = GetDisplayStringValue(a, enumType);
        object enumValue = f.GetValue(null);
        NameEnumPair pair = new NameEnumPair(displayString, enumValue);
        source.Add(pair);
     }
     int index = source.FindIndex(value => value.Value.Equals(property.GetValue(dataSource, null)));
     this.DataSource = source;
     this.Position = index;
  }

  public override bool AllowEdit
  {
     get { return false; }
  }

  public override bool AllowNew
  {
     get { return false; }
     set { throw new NotSupportedException();}
  }

  public override bool AllowRemove
  {
     get { return false; }
  }

  protected override void OnCurrentChanged(EventArgs e)
  {
     base.OnCurrentChanged(e);
     //set the value
     NameEnumPair value = (NameEnumPair)this.Current;
     property.SetValue(dataSource, value.Value, null);
  }

  private static string GetDisplayStringValue(DisplayStringAttribute[] a, Type type)
  {
     if (a == null || a.Length == 0) return null;
     DisplayStringAttribute dsa = a[0];
     if (!string.IsNullOrEmpty(dsa.ResourceKey))
     {
        ResourceManager rm = new ResourceManager(type);
        return rm.GetString(dsa.ResourceKey);
     }
     return dsa.Value;
  }

  private class NameEnumPair
  {
     private readonly string displayName;
     private readonly object value;

     public NameEnumPair(string displayName, object value)
     {
        this.displayName = displayName;
        this.value = value;
     }

     public string DisplayName
     {
        [DebuggerStepThrough]
        get { return displayName; }
     }

     public object Value
     {
        [DebuggerStepThrough]
        get { return value; }
     }

     public override string ToString()
     {
        return DisplayName;
     }
  }
}

All the work happens in the constructor: we use reflection to get the type of the property passed in, get the enum values in the type, read the DisplayStringAttribute values, add them to a list, set the DataSource property, and we’re done. I’ve overridden the AllowXxx properties to make this an immutable BindingSource; there are more properties to override to lock this down as a framework type, but this is a good start. If I were really hardcore, I’d implement all the interfaces that BindingSource does myself, but I don’t see the value.

So, this works for enums that you own, but like I said in the WPF article, that is really rare. What you need is a way to declare the strings for enums that you don’t own. Again, using the WPF implmentation as a reference, we merely need to create a class that will contain the data and set it appropriately. But here, we don’t have the requirement to support XAML, so we have a bit more freedom. Since this is pretty much an immutable type, setting it in the constructor is the way to go. I just need an overloaded constructor. We also need a type to hold the data we want to set. We already have that type with the nested class NameEnumPair, we just need to make it public, and probably move it to the outer scope, as most .NET types are wont to do.

Here’re the new constructors:

public EnumBindingSource(object dataSource, string propertyName)
   : this(dataSource, propertyName, null)
{
}

public EnumBindingSource(object dataSource, string propertyName, IEnumerable<NameEnumPair> overriddenDisplayValues)
{
   this.dataSource = dataSource;
   this.property = dataSource.GetType().GetProperty(propertyName);
   List<NameEnumPair> source;
   if (overriddenDisplayValues == null)
   {
      Type enumType = property.PropertyType;
      FieldInfo[] fields = enumType.GetFields(BindingFlags.Public | BindingFlags.Static);
      source = new List<NameEnumPair>(fields.Length);
      foreach (FieldInfo f in fields)
      {
         DisplayStringAttribute[] a = (DisplayStringAttribute[])f.GetCustomAttributes(typeof(DisplayStringAttribute), false);
         string displayString = GetDisplayStringValue(a, enumType);
         object enumValue = f.GetValue(null);
         NameEnumPair pair = new NameEnumPair(displayString, enumValue);
         source.Add(pair);
      }
   }
   else
   {
      source = new List<NameEnumPair>(overriddenDisplayValues);
   }
   int index = source.FindIndex(value => value.Value.Equals(property.GetValue(dataSource, null)));
   this.DataSource = source;
   this.Position = index;
}

Now we have a way to display enums in ComboBoxes in Windows Forms. Client code looks like the following:

public class MyCustomClass
{
  public MyEnum MyEnumProperty { get; set; }

  public MyCustomClass()
  {
     MyEnumProperty = MyEnum.On;
  }
}

public partial class Form1 : Form
{
  public Form1()
  {
     InitializeComponent();
     MyCustomClass myCustomObject = new MyCustomClass();
     this.comboBox1.DropDownStyle = ComboBoxStyle.DropDownList;
     this.comboBox1.DataSource = new EnumBindingSource(myCustomObject, "MyEnumProperty");
  }
}

private void ArrangeColumnWidth()
{
    //this is called after all the items have been added
    using (Graphics g = this.listView.CreateGraphics())
    {
        int maxWidth = 0;
        foreach (object item in this.listView.Items)
        {
            SizeF s = g.MeasureString(item.ToString());
            if (s.Width > maxWidth)
                maxWidth = s.Width;
        }
        this.listView.Columns[0].Width = maxWidth;
    }
}

Pretty standard find-the-max code, right? Except it wasn’t working. Since I knew there would always be one column, and we’d never change out of Details view, I, without thinking too hard about it, changed the above code to the following:

private void ArrangeColumnWidth()
{
    this.listView.Columns[0].Width = this.listView.Width;
}

“There! That should do it,” I thought — in the few seconds that it took me to write it. Of course, you’ve just read that, and thought, “What a fool! Anyone can see that if there are enough items in the ListView to cause scrolling vertically, then the column width will be too big, so you’ll get a horizontal scroll bar also. Duh! Everyone knows that. What was he thinking?”

And you’d be right.

But sometimes, when I’m in the flow, I have really fast edit, compile, run cycles. The first run after the above edit showed me the problem that you astute readers already found.

At this point, in my younger days, I’d bash away at determining the width of a standard scroll bar and hardcoding that number in my arithmetic. But I’ve learned the following refrain from using .NET since it came out: It’s in the Framework, Dummy!

So, I did a Google search, found a forum post, read it, couldn’t believe the solution was so simple, then went to the MSDN docs to confirm that it was true. It was! If you set the ColumnHeader.Width value to -1, it will size to the largest item. If you set the ColumnHeader.Width value to -2, it will size the header to the header text. It’s all right there on MSDN!

I didn’t know this little tidbit. So, I re-wrote the code. I got rid of the ArrangeColumnWidth() method altogether and now when I create the column, I set it’s width to -1. Problem solved!

Two things occurred to me when I read about those helpful values.

The first is that that is some old-ass .NET code. Microsoft doesn’t write .NET code like that anymore. Instead, I think it would be something like the following:

public enum ColumnWidthStyle
{
    Normal,
    SizeToMaximumItem,
    SizeToColumnHeader
}

ColumnHeader c = new ColumnHeader();
c.WidthStyle = ColumnWidthStyle.SizeToMaximumItem;

That code is more verbose, sure; but it’s way more discoverable, especially with IntelliSense. It’s also more readable; imagine coming back to this code a few months later: it would still make sense. The way we’re stuck with is essentially a magic number, a vestigial bump from the dark ol’ days of Win32 programming. I have no doubt that the ColumnHeader class is managed spackle over the Win32 equivalent, so we get those negative width numbers for free.

Even with the awkwardness of the API as it is, I’m still going to use it. That’s one method I don’t have to write. The whole point of using the .NET framework is that it does a lot for you. And yet…

I still see commercial code shipping with reams and reams of classes and methods that duplicate functionality in the Framework. Why!?!

We’ve all heard the principle of DRY (Don’t Repeat Yourself). I’ve got my own corollary, the DRAFT principle: Don’t Repeat A Framework Type. .NET, J2EE, Rails, Django, CPAN, whatever language and framework you prefer: assume they solve all your problems, learn them, use them, abuse them. And only if they are truly lacking should you write your own.

I recently needed to use this code again, but forgot how I solved it. So, rather than hunt it down on Google again, I came home and loaded up ye olde Windows Live Writer to write this post.

To save the XAML you want as an image, put the elements you want to save into a canvas element called canvas. Then run the following code.

private void CommandBinding_Executed(object sender, ExecutedRoutedEventArgs e)
{
   Rect rect = new Rect(canvas.RenderSize);
   RenderTargetBitmap rtb = new RenderTargetBitmap((int)rect.Right,
     (int)rect.Bottom, 96d, 96d, System.Windows.Media.PixelFormats.Default);
   rtb.Render(canvas);
   //endcode as PNG
   BitmapEncoder pngEncoder = new PngBitmapEncoder();
   pngEncoder.Frames.Add(BitmapFrame.Create(rtb));

   //save to memory stream
   System.IO.MemoryStream ms = new System.IO.MemoryStream();

   pngEncoder.Save(ms);
   ms.Close();
   System.IO.File.WriteAllBytes("logo.png", ms.ToArray());
   Console.WriteLine("Done");
}

I hooked up a key binding to a command to execute this code, but you could use a button click too. It’ll save the elements in canvas to a file in the same folder as the executable, called logo.png, but you can change that if you want. You can also you a different encoder if you like. They’re in System.Windows.Media.Imaging.

Enjoy!

I’m ambivalent towards enums. They are a succinct way of providing a list of choices that don’t change that much. But, I think they are overused, often in situations that don’t lend themselves well to enums. For example, the HttpStatusCode enum in System.Net. It should probably explicitly be a list of constant integers, because that’s the way the status code is thought of to HTTP programmers, well, at least one. Consider the two code snippets below. Which one is more readable?

void ProcessResponse(WebResponse r)
{
    if (r.StatusCode >= HttpStatusCode.BadRequest)
    {
        // handle response
    }
}

void ProcessResponse(WebResponse r)
{
    if (r.StatusCode >= 400)
    {
    // handle request
    }
}

Yeah, yeah: you’re not supposed to use magic numbers, but it’s not like HTTPbis is going to redo all the status codes. It’s a safe bet that the status code with the value 400 will always mean “Bad Request”.

Anyway, Enums are here to stay and we have to deal with them in various ways; displaying them to the user is one way they have to be dealt with. I’ll give a treatment of how to display an enum in WPF in this post. You’ll see that displaying them in all situations is non-trivial.

So, let’s say you want to display a list of the values for your custom enum in a ComboBox in WPF; how do you do it? Well,  you could mess around yourself and test your WPF databinding knowledge, but no one has any patience for that nowadays. Let’s Google it! The goal of most WPF code is to do it all in XAML. So a possible solution to the problem is the following XAML snippet (copied from this post from the WPF SDK blog):

<Window
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:sys="clr-namespace:System;assembly=mscorlib"
  SizeToContent="WidthAndHeight"
  Title="Show Enums in a ListBox using Binding">
  <Window.Resources>
    <ObjectDataProvider MethodName="GetValues"
                        ObjectType="{x:Type sys:Enum}"
                        x:Key="AlignmentValues">
      <ObjectDataProvider.MethodParameters>
        <x:Type TypeName="HorizontalAlignment" />
      </ObjectDataProvider.MethodParameters>
    </ObjectDataProvider>
  </Window.Resources>
  <Border Margin="10" BorderBrush="Aqua"
          BorderThickness="3" Padding="8">
    <StackPanel Width="300">
      <TextBlock>Choose the HorizontalAlignment
                 value of the Button:</TextBlock>
      <ListBox Name="myComboBox" SelectedIndex="0" Margin="8"
               ItemsSource="{Binding Source={StaticResource
                                             AlignmentValues}}"/>
      <Button Content="Click Me!"
              HorizontalAlignment="{Binding ElementName=myComboBox,
                                            Path=SelectedItem}"/>
    </StackPanel>
  </Border>
</Window>

The real magic happens in the bolded text above, the ObjectDataProvider. It calls the GetValues() method on the Enum type. The MethodParameters element contains the actual enum type to display. This is the common sample that you’ll see throughout the web. A couple problems no one seems to address with this solution, though.

The first is the what actually gets shown to the user. For simple one-word values, like the HorizontalAlignment enum used in the XAML sample above (Center, Justify, Left, Right), it’s not a problem — if you’re only coding for the English language. But what about the HttpStatusCode enum? It’ll show up with the Pascal casing BadRequest or RequestedRangeNotSatisfiable rather than “Bad Request” or “Requested Range Not Satisfiable”. That’s acceptable if your audience is a bunch of nerdy programmers (“I actually prefer no spaces, it makes 2.4321% more efficient so I can devote more time to WoW!” Nerd.), but if you’re doing this for real people, you’re going to want a nice grammatically- correct string to show up. You might want even more detail in the string: “Bad Request (400)”, say.

Second, this solution ignores localization. If you just show the name of the enum value, you get whatever language the programmer speaks. That’s fine if you only plan on shipping your product to your country, but what if you are big in Japan? You’re going to want to translate that bad boy to Japanese!

Japan’s calling. Are you going to answer?

Let’s solve that problem.

Let’s first assume that we own the enum type. We have a web product and a WPF product; we use our custom enum type in both products. We want to display the same thing for the enum values in both places. If that’s the case, we want the display strings to move around with the enum. How are we going to do that? Well, we have extra data that we want to move around with a type, perfect for … Attributes!

The simplest attribute class that will work takes a string that will be displayed in place of the enum value. But we don’t want the simplest class that will work. We want one that will also support localization. Still pretty simple and it looks like this:

[AttributeUsage(AttributeTargets.Field)]
public sealed class DisplayStringAttribute : Attribute
{
   private readonly string value;
   public string Value
   {
      get { return value; }
   }

   public string ResourceKey { get; set; }

   public DisplayStringAttribute(string v)
   {
      this.value = v;
   }

   public DisplayStringAttribute()
   {
   }
}

We can apply this to the values of our custom enum, like so:

public enum MyEnum
{
   [DisplayString("My Value")] 
    Value,
   [DisplayString("This means On")]
    On,
   [DisplayString("Off means not On")]
    Off,
   [DisplayString("The great unknown")]
    Unknown,
   [DisplayString("I ain't got none")]
    None
}

Doesn’t look as pretty as an unadorned enum, but commercial quality code often looks less attractive than you’re typical code snippet on MSDN. If we want to internationalize our app, we can have different display strings for different languages by setting the ResourceKey property instead of the value constructor:

public enum MyEnum
{
   [DisplayString(ResourceKey="MyEnum_Value")] Value,
   [DisplayString(ResourceKey="MyEnum_On")] On,
   [DisplayString(ResourceKey="MyEnum_Off")] Off,
   [DisplayString(ResourceKey="MyEnum_Unknown")] Unknown,
   [DisplayString(ResourceKey="MyEnum_None")] None
}

• read the DisplayStringAttribute values applied to our enum class; or
• load the resource string based on the ResourceKey in the DisplayStringAttribute; and
• be expressible in XAML, both declaring one and as a databinding source.

Let’s take care of the third item first, since it will shape the public API more than the other two.

It is an enum’s nature to be static and constant, hence a class that aids in displaying it to the user is also likely to be static. We’ll also be using the EnumDisplayer to convert enum values and as a datasource. Before we can do anything though, we need to know the enum type we’ll be displaying. Ideally, this would mean passing the enum type in the constructor; because of the XAML requirement, however we need a property of type Type. We’ll add a constructor that takes a Type parameter as a convenience for those that like to write everything in code. So our initial public API looks thus:

public class EnumDisplayer : IValueConverter
{
  private Type type;
  private IDictionary displayValues;
  private IDictionary reverseValues;
    
  public EnumDisplayer()
  {
  }

  public EnumDisplayer(Type type)
  {
     this.Type = type;
  }

  public Type Type
  {
     get { return type; }
     set
     {
        if (!value.IsEnum)
           throw new ArgumentException("parameter is not an Enumermated type", "value");
        this.type = value;        
     }
  }

  public ReadOnlyCollection<string> DisplayNames
  {
     get
     {
        this.displayValues =...
        return new List<string>((IEnumerable<string>)displayValues.Values).AsReadOnly();
     }
  }
  
  object IValueConverter.Convert(object value, Type targetType, object parameter, CultureInfo culture)
  {
     return displayValues[value];
  }

  object IValueConverter.ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
  {
     return reverseValues[value];
  }
}

Pretty straightforward public API: two properties, one being the type to generate strings for, and the other, the strings that we generated. The IValueConverter interface is implemented explicitly. The reverseValues dictionary maps the reverse of displayValues: displayValues goes from enum type to string, reverseValues goes from string to enum. This means that each enum value must have a unique display string; hardly unreasonable, since they have to have a unique name within the enum anyway.

The above public API allows us to declare an EnumDisplayer in XAML like so:

<Application.Resources>
        <sm:EnumDisplayer Type="{x:Type FlickrNet:ContentType}" x:Key="contentTypes">
</Application.Resources>

And use it as a data source and value converter:

<ComboBox ItemsSource="{Binding Source={StaticResource contentTypes},Path=DisplayNames}" 
          SelectedValue="{Binding Path=Batch.Photos/ContentType, 
                          Converter={StaticResource contentTypes}}" />

Well, that’s just awesome!

Let’s go back a bit and expand on that ‘…’ in the code for EnumDisplayer. That’s where all the real work happens. Since I don’t know the type at compile time, I use reflection to generate my two IDictionary instances when the DisplayValues property is first accessed. I also inspect the enum type provided for DisplayString attributes. All that code is below. It’s nothing special: most of it I found on the internet if I didn’t already know how to do it.

public ReadOnlyCollection<string> DisplayNames
{
 get
 {
    Type displayValuesType = typeof(Dictionary<,>)
                                .GetGenericTypeDefinition().MakeGenericType(typeof(string),type);
    this.displayValues = (IDictionary) Activator.CreateInstance(displayValuesType);
       
    this.reverseValues =
       (IDictionary)Activator.CreateInstance(typeof(Dictionary<,>)
                .GetGenericTypeDefinition()
                .MakeGenericType(type, typeof(string)));

    var fields = type.GetFields(BindingFlags.Public | BindingFlags.Static);
    foreach (var field in fields)
    {
       DisplayStringAttribute[] a = (DisplayStringAttribute[])
                                   field.GetCustomAttributes(typeof(DisplayStringAttribute), false);

       string displayString = GetDisplayStringValue(a);
       object enumValue = field.GetValue(null);

       if (displayString == null)
       {
          displayString = GetBackupDisplayStringValue(enumValue);
       }
       if (displayString != null)
       {
          displayValues.Add(enumValue, displayString);
          reverseValues.Add(displayString, enumValue);
       }
    }
    return new List<string>((IEnumerable<string>)displayValues.Values).AsReadOnly();
 }
}

private string GetDisplayStringValue(DisplayStringAttribute[] a)
{
     if (a == null || a.Length == 0) return null;
     DisplayStringAttribute dsa = a[0];
     if (!string.IsNullOrEmpty(dsa.ResourceKey))
     {
        ResourceManager rm = new ResourceManager(type);
        return rm.GetString(dsa.ResourceKey);
     }
     return dsa.Value;
}

Reflection code is always so ugly. I warned you it wasn’t pretty! See what framework developers have to go through to make code usable? So what’s happening here?

First, I dynamically create the two dictionaries as generic types. That begs the question: “Jason, why didn’t you use generics, wouldn’t that have been way easier? You’re such a pedantic loser!”

Good question. I couldn’t use them because of that third requirement that I imposed upon myself: XAML. There’s no easy way to declare a generic type in XAML, so I couldn’t use them.

Moving along: Next I grab the custom attributes, look for my DisplayStringAttribute and get the value from it in the helper method GetDisplayStringValue(). Notice I prefer the ResourceKey property before the Value property.

Then I add them to the dictionary and the reverseDictionary.

Astute readers should be asking this question by now: what about that call to GetBackupDisplayStringValue?

Right you are, Dear Reader! You’re so smart.

Alright, let’s go way back to the top of the article and address one of my assumptions: I assumed that I owned the enum type. That’s a great assumption to make when you’re coming up with trivial code examples for a blog post, but what about the real world? I got a mortgage! And WoW bills! And a flight to Japan to pay for!

It’s not an assumption that holds up under scrutiny. In fact, the chances you’ll be using an enum you own is probably slimmer than not owning the type. We all know everyone will be using the awesome DisplayStringAttribute once this blog post is published, but what about enums that were created B. DSA. (Before DisplayStringAttribute). Don’t worry, I got you covered.

To do that, and make it accessible in XAML, we need two things: a collection of enum display overrides and a way to tell the XAML parser that children of the EnumDisplayer get added to that collection. Here’s the rest of the implementation.

[ContentProperty("OverriddenDisplayEntries")]
public class EnumDisplayer : IValueConverter
{
   private Type type;
   private IDictionary displayValues;
   private IDictionary reverseValues;
   private List<EnumDisplayEntry> overriddenDisplayEntries;
   
    ...

   private string GetBackupDisplayStringValue(object enumValue)
   {
      if (overriddenDisplayEntries != null && overriddenDisplayEntries.Count > 0)
      {
         EnumDisplayEntry foundEntry = overriddenDisplayEntries.Find(delegate(EnumDisplayEntry entry)
                                          {
                                             object e = Enum.Parse(type, entry.EnumValue);
                                             return enumValue.Equals(e);
                                          });
         if (foundEntry != null)
         {
            if (foundEntry.ExcludeFromDisplay) return null;
            return foundEntry.DisplayString;
            
         }
      }
      return Enum.GetName(type, enumValue);
   }
   
   public List<EnumDisplayEntry> OverriddenDisplayEntries
   {
      get
      {
         if (overriddenDisplayEntries == null)
            overriddenDisplayEntries = new List<EnumDisplayEntry>();
         return overriddenDisplayEntries;
      }
   }
}

public class EnumDisplayEntry
{
   public string EnumValue { get; set; }
   public string DisplayString {  get; set; }
   public bool ExcludeFromDisplay { get; set; }
}

We decorate our EnumDisplayer class with the ContentProperty attribute that tells the XAML parser that anything contained in an EnumDisplayer element gets added to that property. Then we also need the property which is a List<EnumDisplayEntry>. The EnumDisplayEntry is a way to map an enum value to a new display string. The GetBackupDisplayStringValue() method is pretty straightforward: query the list for the given enum value to return the string or not if you want to exclude from being displayed. I suppose I should prefer the overridden value to the one provided in the DisplayStringAttribute but I’m jonesing for Guitar Hero, so I’m going to wrap up.

The above code enables you to provide your own strings for enum values, which we can express in XAML:

<sm:EnumDisplayer Type="{x:Type FlickrNet:ContentType}" x:Key="contentTypes">
    <sm:EnumDisplayEntry EnumValue="Photo" DisplayString="Photo (Default)"/>
    <sm:EnumDisplayEntry EnumValue="Screenshot" DisplayString="Screenshot"/>
    <sm:EnumDisplayEntry EnumValue="Other" DisplayString="Other"/>
</sm:EnumDisplayer>

Admittedly, these aren’t the most imaginative strings for these enum values, but that’s an actual snippet of XAML from an actual app.

There are still some things to address: WinForms and ASP.NET should be supported. Also, what about Flags enums? How should those be handled? Enums are surprising in their difficultly to show in UI properly. With the enum displayer class we have a good starting point for making a non-trivial problem of displaying enum values somewhat easier in XAML.

So you add one to your project thinking, this’ll be fantastic.

Then it doesn’t work.

You get the following cryptic error:

Unable to set TestContext property for the class {class}. Error:  System.ArgumentException: Object of type 'Microsoft.VisualStudio.TestTools.TestTypes.Unit.UnitTestAdapterContext' cannot be converted to type 'Microsoft.VisualStudio.TestTools.UnitTesting.TestContext'

“So,” you think, “I obviously did something wrong, but it’s not apparent to me what I did. I will check the Google.”

But Google only shows you what to do for the full framework.The answer for the full framework is to delete your reference to Microsoft.VisualStudio.QualityTools.UnitTestFramework, then search for it again in the Add Reference dialog. Microsoft forgot to update all the project templates for VS08, so all of the esoteric projects point to the assemblies for VS 2005. Quality tool, my ass. The full framework instructions don’t make any sense for your awesome Compact Framework assembly. Uh oh, now what are you going to do?

Maybe it’s your project that’s screwed up. So you start a new one to see if it works. It doesn’t, but you get a different error: References root node unavailable. You might as well search the google for that one and then you get this forum post that repeats the solution over and over:

Restart the IDE.

You figure it can’t hurt, so you try it.

And it works.

You can now use unit tests for .NET CF projects, but you’re no longer smiling about it.

If you use Visual Studio, this is obscured from you, but every WPF application must contain the equivalent of the following Main

[STAThread]
public static void Main(string[] args)
{
    Application app = new Application();
    Window win = new Window();
    win.Show();
    app.Run();    
}

Without the Application class, the above program will end right after you run it. The magic in Application.Run() is that it sets up a Win32 message pump so that your whiz bang WPF objet d’art can interact with the rest of Windows, and not exit immediately. There is a surprising amount going on in those four lines of code. Let me explain the big things, before I tell you about the subtlety I found.

There can only be one Application object per process. After the first line of code in the snippet above is run, you can access the static Application.Current property. Doing a test in the Immediate window in Visual Studio to check equality of app and Application.Current will yield true. You can access this anywhere in your app, which makes it really handy.

Let’s continue with executing the second line.

Once the win instance is created, if we were to inspect the app object again, we’d see a few things have changed: the MainWindow property is now non-null — it’s pointing to the win instance; also, the Windows collection will have a Count of 1. For every other window created during the lifetime of the application, the Windows collection will be added to.

Quite a lot has happened in just two lines of code!

The other two lines are obvious; a lot happens when they execute too, but they’re peripheral to the discussion, so let’s move on.

This is a common pattern. Microsoft recognized this and codified it into a pattern. The Application class is designed to be inherited, and a WPF app that doesn’t show a window is a very boring thing. If you create a new WPF application project in VS, you don’t have to write that Main method above; it’s all done for you with code gen in the inherited Application object. You don’t even need to explicitly instantiate a Window instance: VS points the Application.StartupUri property to the XAML file defining your main window.

Now that’s great for one-off demos or simple applications that do the equivalent of turn a light on and off. But, in my experience as a Windows developer, if you want to do anything complicated, your application will have all sorts of configuration to do; or you have to log in to a service to do anything useful; or whatever. Suppose a developer had to code a scenario to show a dialog on the first run of the app to do some absolutely necessary, can’t-run-the-app-without-it configuration. To develop that scenario, one would have to eschew the StartupUri property for something slightly more complex.

The Application class also has a number of important events concerned with application lifetime. One of them is the Startup event. A naive developer would handle the previously mentioned scenario of a config dialog in that event handler, like so:

public class MyApp : Application
{
    protected override void OnStartup(object sender, StartUpEventArgs e)
    {
        if (firstRun)
        {
            MyConfigDialog dialog = new MyConfigDialog();
            if (!dialog.ShowDialog().Value)
            {
                this.Shutdown();
            }
        }
        MyMainWindow window = new MyMainWindow();
        window.Show();
    }
}

If firstRun is true, and you click OK on the dialog, so that ShowDialog() returns true, then the app will shutdown. I know what you’re thinking:

Huh?

I’m not sure, myself: this may be a bug. But here’s what’s going on: if this is the first run of the app, then the dialog is shown. It’s the first Window class created. Therefore, the Application.MainWindow property is set to the dialog instance. When ShowDialog() returns, the dialog is closed. Therefore, Application.MainWindow is null. It’s like that MyMainWindow instance is invisible or something. He could be screaming at the top of his lungs at Application: “HEY, LOOK AT ME! I’VE GOT SOMETHING TO SHOW YOU!”

Then Application just turns around and exits the building.

“ASSH– wait a minute! I’m invisible! I don’t need that stupid App instance. I’m going to rob a bank! I’ll be rich and the ladies will love me.” Then he falls on the floor lifeless, ’cause the whole process died. Poor MyMainWindow.What, you don’t anthropomorphize your objects?

You could also set the MainWindow property yourself, apparently, at any time you want to. But this fails too:

public class MyApp : Application
{
    protected override void OnStartup(object sender, StartUpEventArgs e)
    {
        if (firstRun)
        {
            MyConfigDialog dialog = new MyConfigDialog();
            if (!dialog.ShowDialog().Value)
            {
                this.Shutdown();
            }
        }
        MyMainWindow window = new MyMainWindow();
        //guess what? this doesn't work!
        this.MainWindow = window;
        window.Show();
    }
}

I’m seriously baffled by this. Looking around in Reflector, the code I’m looking at says it shouldn’t act like this. I also don’t touch Application.ShutdownMode (I’ve tested this with OnLastWindowClose and with OnMainWindowClose). Anyway, to workaround the issue, simply ensure that MainWindow is instantiated first:

public class MyApp : Application
{
    protected override void OnStartUp(object sender, StartUpEventArgs e)
    {
        //this works! 
        MainWindow window = new MainWindow();
        if (firstRun)
        {
            MyConfigDialog dialog = new MyConfigDialog();
            if (!dialog.ShowDialog().Value)
            {
                this.Shutdown();
            }
        }
        window.Show();
    }
}

The Application class is a much needed addition to Windows programming. A cross between the ASP.NET Application and Session classes and the WinForms Application class, it provides a property bag, application lifetime events, application-wide resources, an entry point, a Win32 message pump and access to the application’s windows including the Main Window. Architecturally, I find this class very appealing, but that’s a topic for another post.

Just watch out for trying to be fancy with extra windows.

I’m told that the BlogML export always fails in Subtext, which is the same problem I had. If I recall, it would look like it succeeded, but the XML file you got back would be empty. I was using a version that ran on .NET 1.1 (I think around 1.5, but I’m not sure), but the technique I outline below should work for Subtext 1.9.5. I’ll explain (with some code!) how I got around that and it will hopefully help some people out. I had one single-user blog running on Subtext; Multi-user may need far more attention. You will have to get your hands dirty in the code; and by the end of it, you’ll be more familiar with Subtext than you ever wanted to be. I’m writing this from memory, so take whatever I say as a guide rather than gospel. I no longer have a subtext blog set up so I can’t rerun this to see why I made the changes I made. If you’re really determined, you’ll find a way to get your data. I am willing to help anyone extract their posts from Subtext, though. Just contact me through this post, or through the contact form. Maybe we can make this a little more robust to help others.

When I first tried to export using the web interface, as I mentioned, I’d get an XML file, but it would be empty. Bummer! My first thought was that I had to figure out the right query for the database to extract all the posts. Then I would have to format all the posts into some kind of XML format to import into my new blog engine, WordPress. That’s a daunting task when you don’t deal with databases much. Luckily, I played some video games instead of bashing on and realized there was an easier way: using the BlogML exporter in Subtext!

I don’t remember exactly how I came to my solution — maybe I bombed around the code and concluded that the reason it was failing had little to do with the BlogML code? — but it worked, and this was the type of quick one-off problem to which one of my favourite sayings applied: If it’s stupid and it works, it isn’t stupid.

So here’s what I did. I created a ConsoleApplication1 project, referenced just enough of the subtext assemblies (Subtext.BlogML, Subtext.Framework and Subtext.Extensibility) to instantiate their BlogMLWriter and write out the BlogML to disk using an XmlTextWriter. Then I hacked the subtext code to make it compile and run without exceptions. Like I said last time, this solution is not pretty or perfect. To make matters worse, the subtext code I used in my hacked solution was not the same code that my blog was running, so the database versions didn’t match up. Column names had been changed or added; stored procedures had been renamed or added to. This made me do some seriously weird things like tweak stored procedures and DataReaders and I think install stored procedures that weren’t there. I did the types of things that shouldn’t really be recorded for posterity on a blog, you know?

Here’s the only code in my ConsoleApplication1 project:

class Program
{
    static void Main(string[] args)
    {            
        IBlogMLProvider provider = new Subtext.ImportExport.SubtextBlogMLProvider();

        provider.ConnectionString = "yourConnectionString";
        if (provider.GetBlogMlContext() == null)
        {
            Console.WriteLine("ERror'd");
            return;
        }
        BlogMLWriter writer = BlogMLWriter.Create(provider);

        using (XmlTextWriter xmlWriter = new XmlTextWriter("blog.xml", Encoding.UTF8))
        {
            xmlWriter.Formatting = Formatting.Indented;
            writer.Write(xmlWriter);
            xmlWriter.Flush();
        }
        Console.WriteLine("It worked?!");
    }
}

Looks pretty simple, eh? Too bad all the changes are buried deep in completely unrelated classes. I copied the subtext web.config and renamed it app.config. You have to set your connection string in two places in the config file as well as in the Program.cs file shown above (search for ‘yourConnectionString’). Also, since we’re running code written for ASP.NET in a console app, some things simply will not work, like HttpContext.Current. You’ll be shown them quickly after running the first time.

Below is an example of one of the changes I had to make:

private static SqlParameter BlogIdParam
{
    get
    {
        int blogId;
        //if (InstallationManager.IsInHostAdminDirectory)
        //    blogId = NullValue.NullInt32;
        //else
            blogId = 0;

        return DataHelper.MakeInParam("@BlogId", SqlDbType.Int, 4, DataHelper.CheckNull(blogId));
    }
}

This is in Subtext.Framework\Data\SqlDataProvider.cs. See the commented code? InstallationManager, through a number of indirections (like, I don’t know, 57; Subtext is way over-architected) uses HttpContext.Current, so I commented that out. I may have even hardcoded blogId to 0, I don’t remember.

You can download the ConsoleApplication1 project below and try it out if you wish.

Now, if you want to convert BlogML to the WordPress export format…

I work on a .NET application that now runs on 2.0 but was written for 1.1. It’s bit like a farmer’s son who moved to the city and still does things as if he was on the farm. Like mow his two-square-meter lawn with a ride-on mower, "just like daddy used to back home." That’s fine, it gets the job done, but, dude, there’s a better way. Get a push mower, damn it.

Getting it back in the garage is a real bitch

In .NET 1.1, serialization (binary serialization, to be clear) is a bit hairy when you’re successful enough to ship multiple versions of your product and you don’t consider versioning until the first bug report about serialization problems. Changing the type, by either adding or removing fields, in .NET 1.1 causes previous versions of your type to lose their mind. The only way to deal with it at all was to implement ISerializable, which is fraught with problems, not the least of which is it makes you entirely responsible for serialization and deserialization of the whole type for ever and ever.

Now that we’re running on .NET 2.0, we have more options. Microsoft changed the behaviour so that it’s version tolerant by default – no more exceptions on new fields. But there is other awesome stuff besides, so we can have more control over the whole process.

Suppose we had the following serializable type:

//Version 1
[Serializable]
public class MyClass
{
  private string myString;

  public string MyString
  {
     get { return myString; }
     set { myString = value; }
  }
}

You ship your software. MyClass is used to great success; in fact, it made you the most successful MyClass maker in the world. For version 2, you’ve promised big things for your customers. After all the design work your new, improved MyClass becomes the following:

//Version 2
[Serializable]
public class MyClass
{
  private string myString;
  private int myInt;

  public string MyString
  {
     get { return myString; }
     set { myString = value; }
  }

  public int MyInt
  {
     get { return myInt; }
     set { myInt = value; }
  }
}

Oooh, look at all the new features!

MyClass Maker version 2 gets in to QA to test upgrading. All the MyClass version 1 instances upgrade just fine, but you had the good fortune to run on .NET 2.0, which by default doesn’t throw exceptions when there is a field for which the serialized instance does not have data. It just works; Microsoft put serialization in the Pit of Success in .NET 2.0.

But QA came back to Dev with the complaint that after upgrading the MyClass instance didn’t show off the awesomeness of the new features. They think the default value of the new field should be something else. Since you’ve just been reading up on Version Tolerant Serialization, you know just what to do.

What we need is a way to influence deserialization. With .NET 2.0, Microsoft introduced four attributes that deal with serialization process: OnSerializingAttribute, OnSerializedAttribute, OnDeserializingAttribute, OnDeserializedAttribute.

To set a default value for myInt, we create a method with a specific signature and apply the OnDeserializingAttribute to it You could also set the default where you declare the variable if all new instances have the same default, like so:

[OnDeserializing]
private void SetMyIntDefault(StreamingContext sc)
{
   myInt = 42;
}

If you implement ISerializable as well, this method is called before the deserialization constructor. Only one method per class can be marked with each of these attributes. We set the default value in the OnDeserializing method so that, if there is a myInt value in the serialized instance, the default value gets overwritten with the serialized value.

Your marketer just came back from a conference. He really likes this social aspect to these new-fangled web 2.0 applications. Now you’re required to enable sharing of MyClass instances among users. Trouble is, we can’t guarantee everyone is using the most up-to-date version and marketing won’t let us force upgrades. It’s OK, we can deal with that. We just have to tweak our new MyClass version; we’ll mark the myInt field declaration with the OptionalFieldAttribute, so that the serializer will know not to explode if it’s not there. I’m not sure whether this is necessary because during my testing for this article, the presence or absence of OptionalField didn’t seem to matter. But it could be because I was lazy: I didn’t test from 1.1 to 2.0.

[Serializable]
public class MyClass
{
   private string myString;
   [OptionalField(VersionAdded=2)]
   private int myInt;

   public string MyString
   {
      get { return myString; }
      set { myString = value; }
   }

   public int MyInt
   {
      get { return myInt; }
      set { myInt = value; }
   }

   [OnDeserializing]
   private void SetMyIntDefault(StreamingContext sc)
   {
      myInt = 42;
   }
}

Because I’m a good little developer that reads documentation, I included the VersionAdded property in my OptionalField declaration. This is for "future compatibility with new serializers in the framework." I’m not sure there will be other serializers in the framework since the CLR hasn’t changed since 2.0, as well as the whole confusing red bits/green bits thing. But you know what assuming does, right? So I put it in.

One thing I tried in my experimentation was the following: suppose you have a ton of types that implement ISerializable because they’re legacy 1.1 types. As long as you keep the convention of your keys being the same as the name of the field, then you can move the ISerializable implementation to the dustbin. It seems to just work, although I’d test it a little more thoroughly. Suppose MyClass version 1 looked like the below code. In Version 2, you could delete the ISerializable stuff.

[Serializable]
public class MyClass : ISerializable
{
   private string myString;

   public MyClass()
   {
   }

   protected MyClass(SerializationInfo info, StreamingContext context)
   {
      myString = info.GetString("myString");
   }

   public string MyString
   {
      get { return myString; }
      set { myString = value; }
   }

   public void GetObjectData(SerializationInfo info, StreamingContext context)
   {
      info.AddValue("myString", myString);
   }
}

Deleting code you don’t need anymore feels so good. Release yourself from the bonds of ISerializable!

There are so many unsung improvements in the BCL in .NET 2.0 that I’m still finding them nearly four years later. The above improvements to serialization move it from cumbersome chore fraught with peril to those who dare master it to the magic of "it just works." Serialization code is hard to get right, so I’m glad Microsoft took most of the onerous stuff off our hands. I’d encourage you to take a look at the MSDN article on Version Tolerant Serialization for all the details on this stuff. I’ll leave this article with their recommended practices for creating serializable types.

To ensure proper versioning behavior, follow these rules when modifying a type from version to version:

• Never remove a serialized field.

• Never apply the NonSerializedAttribute attribute to a field if the attribute was not applied to the field in the previous version.

• Never change the name or the type of a serialized field.

• When adding a new serialized field, apply the OptionalFieldAttribute attribute.

• When removing a NonSerializedAttribute attribute from a field (that was not serializable in a previous version), apply the OptionalFieldAttribute attribute.

• For all optional fields, set meaningful defaults using the serialization callbacks unless 0 or null as defaults are acceptable.

To ensure that a type will be compatible with future serialization engines, follow these guidelines:

• Always set the VersionAdded property on the OptionalFieldAttribute attribute correctly.

• Avoid branched versioning.

Well, actually, let me leave by adding one more: Don’t implement ISerializable when introducing new types on a .NET 2.0 or greater project. If you can’t serialize your types with the above attributes, you’re doing it wrong.