adamjcooper.com/blog

Casting to a Specific Subclass at Runtime Based on the Value of an NHibernate Discriminator

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Fri, 12 Dec 2008 10:42:57 -1100

So you have a class hierarchy, like this:

Fruit
- Apple
- Orange

Then, when loading persisted instances, your repository returns a Fruit. Fine. But in order to get your work done, you really need an Apple or an Orange. So you need to cast the returned Fruit to its actual type. Fine. Just add a simple read-only enum property to the Fruit class denoting the specific type of fruit. Then, at runtime use that property to determine what cast to make:

if (someFruit.Type == FruitType.Apple)
{
var apple = (Apple) someFruit;

//Do something useful with the apple...
}

Fine. One last wrinkle: you're using NHibernate to persist your objects, and you're using a table-per-class-hierarchy mapping for Fruit (which means you've got a single database table to store any type of Fruit, which is a nice type of mapping if your specific subclasses are light and your parent is heavy).

How do you do this?

Mapping the Enum to a Discriminator

In NHibernate, you use a discriminator to differentiate whether records in a Fruit table are Apples or Oranges (or whatever). But NHibernate discriminators are not mapped to object properties, like our FruitType enum. They are simply an internal way for NHibernate to determine what type of class to instantiate at runtime.

Here's a simple XML mapping example:

<class name="Fruit" table="FRUIT" discriminator-value="fruit">
    <id name="Id">
      <generator class="native" />
    </id>
    <discriminator column="FRUIT_TYPE_COLUMN" />
    ...
    <subclass name="Apple" discriminator-value="apple">
    ...
    </subclass>
    <subclass name="Orange" discriminator-value="orange">
    ...
    </subclass>
</class>

All this mapping is saying is that you have a base Fruit class with two child subclasses, Apple and Orange, which are mapped to a database table named FRUIT. At runtime, NHibernate will know whether a particular record in the FRUIT table is a persisted Apple or a persisted Orange based on the value in the FRUIT_TYPE_COLUMN, which will either be "apple" for an Apple or "orange" for an Orange.

There are a couple of important things to remember about discriminators:

Their default type is string (nvarchar in the database - don't use nchar or you'll get bitten by white space!)
They are not mapped to properties in your object model

Not having any access to the discriminator in your object model is fine if your repository methods return Apples or Oranges specifically, but what if your repository returns a the parent Fruit object? In that case, it would be nice if we did have access to the NHibernate discriminator, preferably mapped to our handy FruitType enum property. Well, there is a way to do this, but it is not obvious.

Basically your mapping needs to declare a discriminator and a property which use the same database column, but you make the property mapping "read only" by turning off database updates and inserts, allowing the discriminator to handle that part instead. Here's a summary:

How to Map an Enum Property to an NHibernate Discriminator Column:

In your database, create an int column that will hold the enum value.
In your NHibernate mapping, declare a discriminator whose type is Int32 (rather than the default string, which won't work with an enum).
In your NHibernate mapping, declare a property mapping which maps to the same column as the discriminator, but be sure to add insert="false" and update="false".

So, here's how our above example would change:

<class name="Fruit" table="FRUIT" discriminator-value="0">
    <id name="Id">
      <generator class="native" />
    </id>
    <discriminator column="FRUIT_TYPE_COLUMN" type="Int32" />
    ...
    <property name="FruitType" column="FRUIT_TYPE_COLUMN" insert="false" update="false" />
    ...
    <subclass name="Apple" discriminator-value="1">
    ...
    </subclass>
    <subclass name="Orange" discriminator-value="2">
    ...
    </subclass>
</class>

With that, our enum property is successfully mapped to the discriminator. But we're not out of the woods yet--there's one last gotcha you need to know about if you're going to be casting at runtime...

No Lazy Loading!

By default, NHibernate uses lazy loading to improve database performance. But in order to do this, NHibernate must create a proxy, something that looks like the type you requested but which is, in reality, a newly derived child type with lazy-loading automatically baked into the associations. What that means is that if your repository method returns Fruit, NHibernate won't give you Fruit, but some sort of FruitProxy_blah_blah_blah, which is a new type derived from Fruit. It is a Fruit, but it's not an Apple, nor an Orange, and if you try to cast to either of them it will blow up in your face.

The good news is that there is a workaround, but the workaround is also the bad news: You must turn off lazy loading. Once you do that you can cast to an Apple or Orange just fine. You just lose all the advantages of the lazy-loading.

So, here's our example re-written once again to support casting at runtime:

<class name="Fruit" table="FRUIT" discriminator-value="0" lazy="false">
    <id name="Id">
      <generator class="native" />
    </id>
    <discriminator column="FRUIT_TYPE_COLUMN" type="Int32" />
    ...
    <property name="FruitType" column="FRUIT_TYPE_COLUMN" insert="false" update="false" />
    ...
    <subclass name="Apple" discriminator-value="1" lazy="false">
    ...
    </subclass>
    <subclass name="Orange" discriminator-value="2" lazy="false">
    ...
    </subclass>
</class>

Conclusion

Exposing a discriminator in your object model as an enum property is easy enough (see above). But if you need to actually use that property to cast the type at runtime, you must turn off lazy loading. If someone knows how to do both, I'd love to hear about it.

Hope it helps.

Happy Birthday!

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Sun, 30 Nov 2008 17:33:00 -1100

The day has finally come! Timothy Stephen Cooper was born on Saturday, November 29, 2008 at 8:37 am, weighing in at 7 lbs. and 5.5 ounces.

Mommy and baby are both healthy and doing well, for which we are very thankful. As with Lydia, Holly elected to give birth naturally (meaning without medication), and she did a fantastic job. No screaming, no crying; just focused, controlled labor. I could not be more proud of her. And because we delivered at a local birth center rather than a hospital, and because there were no major complications during labor and delivery, we were able to go home with Timothy just a few hours after he was born.

It just so happened that I was born 28 years earlier on the morning of the same date, which made this birthday a particularly happy one.

Birthday Pictures

Our family, a few hours after Timothy was born
(after waking up at 6:00 am and being present for the birth, Lydia was a little tired)

Our midwife, who was absolutely wonderful

Timothy, at home and sleeping soundly

Admiring new baby brother

My favorite people

Just after his first bath

Brother-and-sister bedtime

Sons are indeed a heritage from the LORD,
the fruit of the womb a reward.
Psalm 127:3

An excellent wife, who can find?
For her worth is far above jewels.
Her children rise up and bless her;
Her husband also, and he praises her, saying:
Many daughters have done nobly,
But you excel them all.
Proverbs 31:10, 28-29

You formed my inward parts;
You wove me in my mother's womb.
I will give thanks to You,
for I am fearfully and wonderfully made;
Wonderful are Your works,
And my soul knows it very well.
Psalm 139:13-14

Migrating to ASP.NET MVC Beta from Preview 5

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Thu, 16 Oct 2008 19:52:00 -1100

Congratulations to the ASP.NET MVC team, the first official Beta is out. You can download it here.

ScottGu offers an excellent guide to what has changed, and Scott Hanselman and Phil Haack also announce the Beta and summarize what's new. I'll let you read their blogs to get the new features list. I'm going to use this post to outline what I had to do in order to get my existing Preview 5 project converted over to MVC Beta.

Installation

You will need to uninstall Preview 5 (or any other Preview) before you can install the new version.

Update Your References

If you have any projects that are currently depending on the Preview 5 assemblies, you will need to remove the references to these assemblies and then add references to the new assemblies. Specifically, you need to update:

System.Web.Abstractions.dll
System.Web.Mvc.dll
System.Web.Routing.dll

The new assemblies are typically located in C:\Program Files\Microsoft ASP.NET\ASP.NET MVC Beta.

The installer apparently also places these assemblies in the GAC, but I don't recommend using them this way. First, the .NET tab of the Add References dialog is mysteriously missing System.Web.Mvc (though it contains .Abstractions and .Routing). But more importantly, if you want to deploy to your web server without having to change anything on the server itself, you should add local references for these three assemblies.

Use Local Copies of the MVC Assemblies for Easy Deployment (Avoid the GAC)

I had an issue with my application running fine on my local machine but not on the web server that turned out to be a GAC/local bin conflict. I had added references to the MVC assemblies by browsing to C:\Program Files\Microsoft ASP.NET\ASP.NET MVC Beta, like so:

However, each of these references had "Copy Local" set to False, and my web.config file contained assembly references in the compilation section that referenced the GAC. So, when I ran on my local machine, the GAC assemblies were present and it worked fine. But when I pushed out to the server, the MVC assemblies were not included in the local bin folder, and since the MVC Beta installer hadn't been run on the web server, it obviously didn't work.

The solution is to make sure that the MVC assemblies have Copy Local set to True, which ensures that you get a copy of the assembly in the local bin folder:

And you can remove any lines in your web.config that reference the GAC versions:

If I'm misrepresenting something here someone let me know.

Futures Assembly (Microsoft.Web.Mvc.dll)

If you have any references to the ASP.NET MVC Futures assembly (Microsoft.Web.Mvc.dll), it will also need to be updated. However, now that MVC has entered Beta status, the Futures assembly is no longer being included in the installer. You will need to download the updated Microsoft.Web.Mvc.dll, updated for MVC Beta, from CodePlex.

Rebuild Your Projects and Correct and Breaking Changes

If you're lucky, all you'll need to do is update your references, rebuild, and you're done. If you're like me, you'll hit a few snags along the way and need to make some changes to your code.

Gotchas

Here's what got me when I updated to MVC Beta:

ActionLink Bug?

I tried using one of the new ActionLink overloads, specifically ActionLink(string linkText, string actionName, string controllerName, object values) but I could never get it to produce a link with a correct href. Instead of a valid URL, I'd get a URL that had a ?Length=n tacked onto the end of it, where n was the length of the controllerName string. Very strange, and very frustrating. Has anyone else noticed this?

Strongly-typed Html.ActionLink moved to the Futures Assembly

The strongly-typed version of ActionLink is now in the ASP.NET MVC Futures assembly (Microsoft.Web.Mvc). If you want it back, you'll need to download the new Beta-compatible Futures assembly from CodePlex and add it to your project.

ViewContext.ViewName Removed

I'm not sure why. In the meantime, you can use the much uglier ViewContext.RouteData.Values["action"].ToString(). But I'd sure like to see that property come back (or at least get a good explanation of why it disappeared).

AddModelError Changes

If you were using the ViewData.ModelState.AddModelError method, you'll notice the second parameter, attemptedValue, is gone. That's because the there's a new, independent SetAttemptedValue method you should use instead. This makes sense--you may need to set multiple errors for a single attempted value, so the two operations should be teased apart.

Html.Form is now Html.BeginForm

If you're looking for the Html.Form helper method, it's now named Html.BeginForm. Scott Guthrie elaborates.

MvcContrib.Ninject

I'm currently using Ninject in combination with NHibernate. With Preview 5 I was using the Ninject support offered in MvcContrib, but this doesn't work with MVC Beta. The good news is that the latest version of Ninject comes with its own, more streamlined support for ASP.NET MVC, and it works fine with the Beta version. I may blog more about the details in a future post, but the short story is this: You need to checkout the latest version of the Ninject source code (svn checkout http://ninject.googlecode.com/svn/trunk/ ninject-trunk), add references to Ninject.Core.dll, Ninject.Conditions.dll, and Ninject.Framework.Mvc.dll to your MVC project, and then update your Global.asax file as outlined in Emad Ibrahim's blog: http://www.emadibrahim.com/2008/08/21/ninject-killer-ioc/.

Why I Abandoned Silverlight for ASP.NET MVC

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Sat, 11 Oct 2008 17:13:00 -1100

I'm currently tasked with building a web-based tool that helps social event coordinators keep track of their invitees--who has been contacted, who has sent in an RSVP, who has paid, what particular activities a person will be participating in, etc. It's essentially a big contacts list with a lot of enhanced functionality around registration and payment. The basic domain model and data layer are in place, and I've spent the past month building a user interface in Silverlight. It's been an interesting journey, and there's a lot about Silverlight that I really, really like, but in the end I've finally decided a monolithic Silverlight application is not the right path. I probably should have heeded Shawn Wildermuth's warning about not building a monolithic Silverlight line-of-business application before I got started, but it's hard to know how to use or how not to use a platform if you've never built anything with it. So I tried, and it was working, but in the end it just became too laborious.

Why? Because even though Silverlight has a super-cool UI model, gives you mini .NET framework, and let's you program in C#, it still can't give me what I really want: my domain objects.

Traditional web applications are strange in that the server is responsible--in one way or another--for building and adjusting the UI that will run on the client. Stop and think about that. JavaScript aside, the client is just a dumb terminal, and the server is in command. Web 2.0 has changed a lot of that, with AJAX frameworks that are putting more burden on the client, but the fact that the initial rendering of so many web UI's is still done server-side shows the strange sort of blurring of the client/server boundary line that exists in traditional web development.

Silverlight, on the other hand, makes a complete break. It is the client in command. At runtime it is the client itself which builds the UI and which is responsible for updating it, not the web server. That is a big paradigm shift from traditional web development and it brings with it some consequences, one of which is interaction with your domain model. In a traditional web app you can dynamically build up the HTML to send to the client using the domain model that lived on the server. But in Silverlight, any part of the UI that depends on server-side assemblies will need to make calls to the server to maintain itself. At first this doesn't seem so bad since Silverlight comes with an impressive networking stack. But after a month of laborious and painful development, I've finally decided it's just too complex for my style of development.

Now, if you're not particularly interested in being domain-driven, if you just need to get the data into the UI so you can mess with it, you can probably get a basic data-driven Silverlight app running without too much hassle. But if you like to build robust domain models that the UI layer depends on, you need to carefully consider the development cost of using a UI platform that requires you to do all of your communication with your domain model via web services and forbids you from dynamically building the UI on the server (unless you're planning to send XAML over the wire).

For the application I've been developing it wasn't that Silverlight wasn't capable of doing what I wanted, but that what I wanted took too long to do and required too much busywork. Here is a summary of my pain points:

Data Transaction Objects. Sprinkling my domain model with lots of WCF data contract attributes was out of the question, not only because I didn't want to pollute the model, but because not everything that needed to go over the wire was in the form of a property. So a lot of the hassle came from the unavoidable evil of converting domain objects to stale DTOs and then re-hydrating them after they come back from the client. The conversion to and from a DTO involved lots of mundane property assignments with sprinkles of complexity to handle constructors, immutable types, and lists. It wound up being an unusual combination of boring and yet error-prone code that required a lot of maintenance.

WCF Service Configuration. It took a lot of head-banging to figure out how to successfully update my WCF services during development, and it only got uglier when I implemented ASP.NET-based authentication to keep the services locked down. Eventually it became second nature, but I spent an awful lot of time adjusting authentication in web.config, deleting the service reference in the Silverlight project, re-adding it, etc.

The Lack of SOAP Faults. This one really got to me. The inability for exceptions to travel across the wire as SOAP faults was extremely frustrating. It made debugging difficult, and sending useful error messages cumbersome. I wound up wrapping all of my service return values to include a possible exception information object. What a mess.

The Lack of Domain Object Functionality. Initially the idea of a pure separation of client/server was very attractive to me. After all, why should the burden of updating the user interface be split between the client and server as in most Web 2.0 web apps? But in practice, the inability to send the functional side of my domain objects across the wire made things difficult. I realize this is what services are for, but there were so many times when I had a simple problem to solve and the web services barrier was getting in the way.

For example, my domain model includes a rather robust object for a person's name (first, middle, last, friendly, preferred, prefix, suffix, etc.). I also have a PersonNameFormattingService object which I use to build different strings, from the formal "Dr. L. David McClister" to the simpler "McClister, Dave". There are even methods to take a current and former name to generate a name string that includes a maiden name. The point is that all of that formatting logic is housed in the PersonNameFormattingService, on the server, and I don't want to duplicate it.

Now, on the Silverlight side, there were lots of times when I needed a person's name formatted in different ways. But the service I need to format the data lives on the server. This left me with two options, neither of which I liked: 1) create an identical PersonNameFormattingService in a Silverlight library that does essentially the same thing, or 2) format the name on the server and send the result over the wire as needed.

The problem with the first approach is that it forces me to update two copies of the code base. And, while it may work just fine for simple name formatting, if it involves heavier lifting in the .NET framework, it may not be entirely portable to a Silverlight library. It's an option to consider, but it's not a silver bullet. The problem with the second approach is that it's a big hassle, and it forces you to build lots of services and DTOs just to get leverage your domain model logic. This is just one example. I fought this sort of stuff on a daily basis. It seemed the more robust my domain model, the more difficult it was to use.

I'm sure experienced SOA developers would have better intuition than I do about how to organize and build services and DTOs to appropriately leverage their domain layer from a remote Silverlight client, but I got to the point where I was spending more time building a bridge to access my domain model rather than using the model to get real work done.

So now I'm using ASP.NET MVC, and I'm loving it. I can build a clean, testable UI layer that leverages the full power of my domain model. Add in some jQuery for AJAX, and I can leverage the client to get partial page updates while still leveraging the server to generate the UI. From my perspective, a beautiful compromise.

Visual Studio Power Commands Crashing Visual Studio When Opening a File

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Thu, 25 Sep 2008 17:52:00 -1100

I finally found the source of a problem that's been plaguing me for a while: When working in Visual Studio I'll double-click on a file and, rather than opening the file, Visual Studio simply closes. No error message, no explanation, just a vanishing IDE. Typically a restart of Visual Studio solves the problem, but I just finished installing ASP.NET MVC Preview 5 and now my IDE is closing every time I try to open an .aspx view page, regardless of how many times I restart (or reinstall!) Visual Studio.

I finally found the problem: the Visual Studio Power Commands plugin. After uninstalling it, I can open my files just fine. Thanks to Tim Van Wassenhove and many others on Phil Haack's blog who pointed out the problem.

Improved Mouse Wheel Support for Silverlight 2 Beta 2 ScrollViewer

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Tue, 09 Sep 2008 08:48:00 -1100

This is an update to a previous post, but everything you need to easily add mouse wheel support to a Silverlight 2 Beta 2 ScrollViewer is listed here.

The Problem

Silverlight 2 Beta 2's ScrollViewer control doesn't recognize the mouse scroll wheel, and implementing a workaround is difficult for two reasons: 1) the only way to listen for mouse wheel events is via the browser which hosts your Silverlight app, and 2) the ScrollViewer control doesn't always fire the MouseLeave event when the mouse exits on the side where the scroll bar is, making it extremely difficult to know exactly which ScrollViewer the user is currently hovering over.

Problem #1 has been solved fairly well by Jeff Prosise and Peter Blois, but since they were interested in using the wheel for deep zoom and not the ScrollViewer, problem #2 was still left to be tackled.

The Solution

I've created a small static class that you can use to easily "attach" mouse wheel support to your scroll viewers as your application is initializing. You basically set-and-forget each ScrollViewer and instantly get mouse wheel support.

Demos

Here are a couple of demos to show it in action:

Default Behavior: Association by Hover

The default behavior is for the mouse wheel to affect which ever ScrollViewer is most immediately under the cursor at the time of the last mouse movement.

Click here to run the default (hover) behavior demo...

Alternative Behavior: Association by Focus

Alternatively, you can modify one method call to change the default behavior from hover-to-associate to click-to-associate.

Click here to run the focus behavior demo...

Usage

Give Your ScrollViewers a Solid Background

Even if you use my workaround API correctly, a ScrollViewer without a background won't always get registered with the mouse wheel. So make sure you give your ScrollViewers a non-transparent background, even if it's the same color as the background of the element behind it. If you don't, the scroll wheel will only work when the mouse is interacting with non-whitespace in the ScrollViewer, which is generally not what you want.

Initialize the Static Helper Class Exactly Once at the Root of the Application

Your root control needs to call ScrollViewerMouseWheelSupport.Initialize for everything to work correctly, like this:

public partial class MouseWheelDemo : UserControl{    public MouseWheelDemo()    {        InitializeComponent();        //Initialize the static scroll viewer mouse wheel support class by providing a reference to the root visual.        ScrollViewerMouseWheelSupport.Initialize(rootVisual);        .        .        .

Where rootVisual is the root element of your application (usually it's easiest to just give an instance name to the root element in your XAML and use it here).

If you prefer the associate-by-click model, just call the Initialize method like so:

ScrollViewerMouseWheelSupport.Initialize(rootVisual, MouseWheelAssociationMode.OnFocus);

The important thing to know is that this method should only be called once by the entire application. You don't need to call it for each control, just for the application itself.

Register Multiple ScrollViewers Correctly

Single ScrollViewer

If you only have one ScrollViewer on the page, all you need to do is use the AddMouseWheelSupport extension method, like so:

//Register a single scroll viewersingleScrollViewer.AddMouseWheelSupport();

Multiple ScrollViewers

If you have multiple ScrollViewers--including any ScrollViewers that are part of controls such as drop-down menus or combo boxes that you'd like to add mouse wheel support for--then you need to know a few things about the proper order of registration (if you get it wrong, you'll get strange results).

Internally my implementation keeps track of a tree of all of the ScrollViewers in the app which have been registered for mouse wheel support. I've done my best to hide all the details under the hood, but I do require that you follow a particular order of registration: ScrollViewers which contain child ScrollViewers must be registered first before any of their children can be registered.

I've overloaded the extension method to make registering multiple ScrollViewers a little bit easier, but ultimately everything can be done with a single method whose signature is:

public static ScrollViewer AddMouseWheelSupport(this ScrollViewer parentScrollViewer, ScrollViewer childScrollViewer, double scrollAmount)

Technically you could do everything with just this method. If you were adding a root ScrollViewer that didn't have a parent at all, you could call this as a simple static method (rather than an extension method) and pass in null for the first argument. But it's a lot easier to use an overload like this, which also provides a default for the scrollAmount:

myScrollViewer.AddMouseWheelSupport();

Let's say you have three ScrollViewers and scrollViewer1 contains scrollViewer2 which contains scrollViewer3.

Here's the long way to wire them up:

ScrollViewerMouseWheelSupport.AddMouseWheelSupport(null, scrollViewer1, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(null, scrollViewer2, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(null, scrollViewer3, 30.0);

Or, you could tighten things up with these fluid overloads:

ScrollViewerMouseWheelSupport    .AddMouseWheelSupport(scrollViewer1)    .AddMouseWheelSupport(scrollViewer2)    .AddMouseWheelSupport(scrollViewer3);

Both do exactly the same thing; the second version is just cleaner. It begins by using an overload which passes in null for the parent and then returns scrollViewer1. The next two calls use the returned ScrollViewer as the parent and set up a specified child (scrollViewer2 is added as a child to scrollViewer1, and scrollViewer3 is added as a child to scrollViewer2).

Or, let's say you have one parent with four children--A, B, C, D--like this:

Here's the long way to add mouse wheel support to all 5 ScrollViewers:

ScrollViewerMouseWheelSupport.AddMouseWheelSupport(null, parent, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(parent, childA, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(parent, childB, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(parent, childC, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(parent, childD, 30.0);

And here's the short way:

parent.AddMouseWheelSupport();parent.AddMouseWheelSupport(childA);parent.AddMouseWheelSupport(childB);parent.AddMouseWheelSupport(childC);parent.AddMouseWheelSupport(childD);

The API allows for variation, but that's the basic usage.

Limitations

This only works with ScrollViewer. It does not affect any other scrolling control (such as a ListBox).

Download

Here is a zip archive of a Visual Studio 2008 SP1 solution that contains the workaround source code in its own project/assembly (Cooper.Silverlight.Controls) as well as the source for the demos listed above:

Solution with Source Code and Demos (ScrollViewerMouseWheelDemo.zip)

Mouse Wheel Scrolling in Silverlight 2 Beta 2

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Mon, 08 Sep 2008 19:59:00 -1100

UPDATE

I've put together a much improved new version that includes support for associating the mouse wheel by simply hovering over a ScrollViewer, as well as live demos and a more complete download example.

Consider this post and the download deprecated. Please see the new post.

Introduction

So our company decided to go ahead with Silverlight 2 Beta 2 as the platform for our next application. Then one day during the middle of our development cycle we discovered that the ScrollViewer control doesn't recognize the mouse wheel. Great. For a while we ignored it and were hoping Microsoft would release Silverlight 2 and solve the problem. Well, the Olympics came, and the Olympics went. Still no word on Silverlight 2. My best guess now is an update at PDC 2008 in October. But the unsettling silence from Redmond regarding Silverlight's future means we may be waiting a while, and I'm tired of waiting.

So, with a big head start from Jeff Prosise and Peter Blois, I implemented a one-line extension method that adds mouse-wheel scrolling support to any ScrollViewer. All you need to do is call the method when your XAML page is getting setup:

public partial class MyXamlPage : UserControl{    public MyXamlPage()    {        InitializeComponent();        //Enables mouse wheel scrolling to this ScrollViewer instance        scrollViewer.AddMouseWheelSupport();    }}

Why Not Extend ScrollViewer?

Because ScrollViewer is a sealed class. This made coming up with a solution extremely difficult.

Behavior: A Focus/Blur Model

NOTE: The new version solves this problem and offers both a hover and focus behavior models.

The mouse wheel will only affect a particular ScrollViewer when the ScrollViewer is in focus. What this means is that you'll need to click on the ScrollViewer's contents (or tab to it) before the wheel will do any scrolling.

This is not what I wanted. I would have preferred for the mouse wheel to simply affect whatever the top most (as in z-index) ScrollViewer, whichever one happens to be directly under the cursor at the time the wheel turns. Doing this would be cake if it weren't for a flaw in the ScrollViewer's MouseLeave event. If MouseEnter and MouseLeave were guaranteed to always fire, you could use a simple stack to keep track of which ScrollViewer is currently top-most by pushing a ScrollViewer whenever mouse rolls in and popping a ScrollViewer whenever the mouse rolls out. Unfortunately, the ScrollViewer in Silverlight 2 Beta 2 only guarantees a MouseLeve event on three sides of the box: the side with the scroll bar doesn't always fire. As far as I can tell this flaw makes automatically associating the top-most ScrollViewer with the mouse wheel a practical impossibility.

So, for now, we have to rely on the GotFocus and LostFocus events and settle for a model where the user must explicitly click on a ScrollViewer before the mouse wheel can control it. Some might argue this is actually the better model of the two since you don't get any nasty surprises when scrolling over content that itself contains another scrollable region (don't you hate it when you're racing the mouse wheel down a page and then you get "snagged" on some other scrolling region that you don't want to scroll through?). But that said, I still think the advantages of a MouseEnter/MouseLeave model are better than those of a GotFocus/LostFocus model. If someone sees a straightforward way to modify my solution to do that, please let me know.

Usage

Give Your ScrollViewer a Solid Background

Because the ScrollViewer must receive focus before the mouse wheel can affect it, leaving the background empty/transparent is not a good idea. Why? Because when your user tries to click on some empty space in the ScrollViewer attempting to register focus, they'll be frustrated to find it only works when they click on top of some text, a graphic, or a form input. But if you give the ScrollViewer a non-transparent background brush, your users can click anywhere in the ScrollViewer and Silverlight will fire the GotFocus event just fine.

Register Multiple ScrollViewers Correctly

If you only have one ScrollViewer on the page, just call the AddMouseWheelSupport as I did in the above example.

However, if you have multiple ScrollViewers--including any ScrollViewers that are part of controls such as drop-down menus or combo boxes that you'd like to add mouse wheel support for--then you need to know a few things about the proper order of registration (if you get it wrong, you'll get strange results).

I've overloaded the extension method to make registering multiple ScrollViewers a little bit easier, but ultimately everything can be done with a single method whose signature is:

public static ScrollViewer AddMouseWheelSupport(this ScrollViewer parentScrollViewer, ScrollViewer childScrollViewer, double scrollAmount)

myScrollViewer.AddMouseWheelSupport();

Let's say you have three ScrollViewers and scrollViewer1 contains scrollViewer2 which contains scrollViewer3.

Here's the long way to wire them up:

ScrollViewerMouseWheelSupport.AddMouseWheelSupport(null, scrollViewer1, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(null, scrollViewer2, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(null, scrollViewer3, 30.0);

Or, you could tighten things up with these fluid overloads:

ScrollViewerMouseWheelSupport    .AddMouseWheelSupport(scrollViewer1)    .AddMouseWheelSupport(scrollViewer2)    .AddMouseWheelSupport(scrollViewer3);

Or, let's say you have one parent with four children--A, B, C, D--like this:

Here's the long way to add mouse wheel support to all 5 ScrollViewers:

ScrollViewerMouseWheelSupport.AddMouseWheelSupport(null, parent, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(parent, childA, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(parent, childB, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(parent, childC, 30.0);ScrollViewerMouseWheelSupport.AddMouseWheelSupport(parent, childD, 30.0);

And here's the short way:

parent.AddMouseWheelSupport();parent.AddMouseWheelSupport(childA);parent.AddMouseWheelSupport(childB);parent.AddMouseWheelSupport(childC);parent.AddMouseWheelSupport(childD);

The API allows for variation, but that's the basic usage.

Code Listing and Download

The code listing and download have been removed in favor of the newer, improved version.

Getting WCF Services Running on IIS 6

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Fri, 29 Aug 2008 03:36:00 -1100

Getting WCF services up and running on IIS 6 isn't hard if you know what to do. Here are the high points:

Make sure ASP.NET is installed and registered with IIS on your web server
Make sure WCF (.NET Framework 3.0/3.5) is installed
Make sure that the .svc extension is mapped to the ASP.NET ISAPI dll in IIS

For me, it was point 3 that was the big problem. I found a lot of advice on various forums saying I should run the ServiceModelReg.exe tool to re-register the mapping and then restart IIS, but it never took. continued to receive HTTP 405 errors when trying to access the service, and apparently I'm not the only person who had this problem as evidenced by this forum post.

The solution was simple: I needed to add a mapping for .svc in IIS 6. It's not hard if you've done it before, but if you're not used to IIS 6's sometimes illogical user interface you can waste a lot of time poking around with the mouse. So here's a step-by-step guide.

How to Add the .svc Mapping to IIS 6

Open Internet Information Services (IIS) Manager:

Right-click on the website (or an individual web application) that needs the .svc mapping, then click Properties:

Go to the Home Directory tab and click the Configuration button:

Click the Add... button to add a new application extension mapping:

Set the Executable field to the location of the ASP.NET ISAPI dll, typically C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll

Set the Extension field to .svc

Accept the default values for everything else and click OK

And that's it. Assuming you have ASP.NET and WCF (.NET 3.0/3.5) installed correctly on the server, adding this mapping should allow you to correctly serve up WCF services in your ASP.NET website (URLs that end in .svc).

(Note that if you're adding this mapping to a website that has some applications with the mapping already in place, IIS will ask you to confirm if the new value should overwrite the old.)

How to Quickly Connect and Disconnect from a VPN by Leveraging the Command Line

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Tue, 05 Aug 2008 04:53:00 -1100

One of the things I dislike about Windows Vista is how many clicks it takes to connect to a VPN, and how I must wait for the connection to be completely established just to dismiss window when it is successful. I do most of my work remotely and connecting and disconnecting to and from a VPN is a part of my daily routine. I finally broke down today and found a faster way to connect and disconnect to and from a VPN.

Using the Command Line

First things first: you can connect to any of your VPNs using the rasdial command from the command line.

Here's the format to connect:

rasdial entryname [username [password|*]] [/DOMAIN:domain] [/PHONE:phonenumber] [/CALLBACK:callbacknumber] [/PHONEBOOK:phonebookfile] [/PREFIXSUFFIX]

And here's the format to disconnect:

rasdial [entryname] /DISCONNECT

For example, if your VPN is named "My VPN", your username is "johndoe" and your password is "password123", you could connect to the VPN from the command line like this:

rasdial "My VPN" johndoe password123

When you're finished, you can disconnect like this:

rasdial "My VPN" /DISCONNECT

Using Shortcuts

Once you've successfully connected and disconnected from the command line, it's a piece of cake to create a new windows shortcut that you can execute at will anytime you need to connect or disconnect. Just choose a folder were you want to shortcut to live, right-click, click New, click Shortcut, and in the dialog that comes up simply paste your tested command line text into the box that is labeled "Type in the location of the item," like so:

Click Next, then give this shortcut a name, like "My VPN Connect":

Click Finish, and you're done. Now you have a dedicated shortcut for connecting to your VPN:

Follow the same procedure to create a corresponding "My VPN Disconnect."

Using a Launcher

I keep all of my VPN Connect/Disconnect shortcuts in a single folder that I've cataloged with my launcher (Launchy). Now all I have to do to connect or disconnect from a VPN is hit my launcher hot key, type a few letters of the shortcut and hit enter when I get what I'm after:

No more hunting through the Windows Vista "Connect to a Network" list to find my VPN and then waiting for it to connect just so I can close the window that tells me it worked. Now I can connect or disconnect in just a few keystrokes.

More Tips...

If you find information like this helpful, I highly recommend Neal Ford's new book, The Productive Programmer. He spends an entire chapter covering useful applications and tricks that you can use to accelerate your work.

Another Look at FireFox's Keyboard Shortcuts - A Lesson in How to Choose Your Shortcuts Wisely

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Sat, 02 Aug 2008 04:05:00 -1100

When first learning keyboard shortcuts, I typically look for a English relationship between the letter of the shortcut and the function I need to accomplish. But for some shortcuts, the letter chosen seems to have no connection with a word that's related to what you're trying to do. That's because there are really two types of letter-based shortcuts: 1) shortcuts chosen for their connection with a word, and 2) shortcuts chosen for their location on the keyboard.

For example, in Windows we're used to common shortcuts like Ctrl+S for Save, Ctrl+B for Bold, Ctrl+I for Italic, and so on. But we're also used to things like Ctrl+Z for Undo, Ctrl+X for Cut, and Ctrl+V for Paste. Why didn't they choose Ctrl+U for Undo? Because Ctrl+Z is easier to press, and Undo is a function we use a lot. The same is true for Ctrl+V: 'V' has nothing to do with the word "Paste," but the function of pasting is so related to the function of copying, it's nice to have the copy and paste shortcut keys next to each other. Actually, the keyboard shortcut letters for Cut, Copy, and Paste (X, C, V) seem to have been chosen primarily for their location on the keyboard. The fact that 'C' matches Copy and 'X' has a linguistic association with Cut is just an added bonus.

FireFox also includes a healthy mix of word-based and location-based Ctrl-key shortcuts. For example, Ctrl+T for a new Tab, Ctrl+P to Print, Ctrl+R to Reload, etc. But there are also many other keyboard shortcuts that have been chosen strictly for their location on the keyboard. Take a look:

Most of these letters have nothing to do with their associated action, but they are very comfortable to use. Notice the grouping of Ctrl+L and Ctrl+K. Like the shortcuts for Cut, Copy, and Paste, getting into the Location Bar and getting into the web search box are common functions and go well together. The addition of Ctrl+J hanging off to the left to open the list of downloads is also appropriate, since it's also a function that involves navigation (though on the local file system).

Once I discovered the reasoning behind why certain FireFox shortcut keys were chosen, it helped me to start using them more frequently. Location-based shortcut keys aren't as obvious, but they are a pleasure to use.

A well-designed application will choose its keyboard shortcuts based on location and ease-of-use while at the same time choosing obvious language-based associations when possible to aid in memorization. Save is a common function, and Ctrl+S is easy to press, so choosing S as the letter of the shortcut makes sense. But when you're setting up a shortcut for a commonly used application function and the most obvious letter is already taken or is not easy to reach, pick one that's easy to press and forget about the letter.

Ninja-Speed Browsing With FireFox Keyboard Shortcuts

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Fri, 01 Aug 2008 18:59:00 -1100

FireFox is full of keyboard shortcuts that can dramatically increase your web browsing productivity if you spend a little bit of time learning them.

As an example to whet your appetite, consider the following workflow:

You need to execute a web search and place the results in a new tab
What you're looking for is the first result in the list
You click the link

How do you do this? If your answer is "I would move my hand off of the keyboard, grab my mouse, click the search bar at the top of the browser, move my hand back to the keyboard, type my search, press enter, realize I need to click the first item in the list, move my hand back to the mouse, and finally click the first result in the list," then you're browsing the way I did for so long: slow.

Here's how you would do this in FireFox using the keyboard:

Ctrl + K - This moves you to the search box (you can also use Ctrl + E, but I use the pneumonic looK to remember Ctrl + K as being associated with search).
Type your search and press enter.
Press the ' key - This opens a find tool that only searches for link text, really handy when you want to move the focus to a link without grabbing the mouse.
Type in a few identifying characters of the link you want to "click." For example, if the result in the list you need to click says "How to browse faster," you might type "browse fas." If you don't "hit" the link you're trying to click the first time, press F3 to go forward to the next link-search result or Shift + F3 to go backward until the link you're after is highlighted.
Press enter.

Try it for yourself. You can get around the web very quickly this way.

Beginner's Guide to Keyboard Browsing

Here are some of FireFox's keyboard shortcuts. I've tried to categorize the keyboard shortcuts by practical use. You should be able to read this list from top to bottom and "discover" how to drive FireFox with the keyboard. In fact, I would encourage you to open a browser and work your way through this list to see just how easy it is to command from the keyboard.

The Fundamentals

Select the location (address) bar	Ctrl + L (for Location) or Alt + D
Open location	Enter while in the location bar
Open location(or search result) in a new tab	Alt + Enter while in the location bar (or web search box)
Auto-add "www." and ".com" to what you've typed in the location bar (i.e. type "amazon" and have FireFox automatically convert it to "www.amazon.com")	Ctrl + Enter after typing in the location bar
Auto-add "www." and ".net" to what you've typed in the location bar (i.e. type "silverlight" and have FireFox automatically convert it to "www.silverlight.net")	Shift + Enter after typing in the location bar
Auto-add "www." and ".org" to what you've typed in the location bar (i.e. type "blender" and have FireFox automatically convert it to "www.blender.org")	Ctrl + Shift + Enter after typing in the location bar
Scroll within the page	Up and down arrows for single line, page up and page down for page
Click a link	Press the ' key to "search" the page for links. Type in part of the link text, ideally a part that is unique on the page. If necessery, use F3 and Shift + F3 to cycle forward/backward through the links on the page which match your search. Once the link is highlighted, press enter.
Back	Ctrl + Left Arrow
Forward	Ctrl + Right Arrow
Open a selected link in a new tab	Ctrl + Enter
Open a selected link in a new window	Shift + Enter
Switch tabs	Ctrl + [0-9] - You can immediately switch to any of the first 9 tabs you might have open by pressing Ctrl plus a number key (i.e. Ctrl + 3 switches to the third tab from the left).
Close the current tab	Ctrl + W or Ctrl + F4, much like Alt + F4 closes an entire window.
Open a new tab	Ctrl + T
Open a new window	Ctrl + N
Move to the browser's web search box	Ctrl + K (as in looK) or Ctrl + E (as in googlE or livE)
Switch the current search engine in the search box	While in the search box (Ctrl + K), press Ctrl + Down Arrow or Ctrl + Up Arrow to move through the search engine options.
Bookmark current page	Ctrl + D
Selecting text	Press F7 to start "Caret Browsing" mode. Basically FireFox puts a caret in the middle of the page much like you would see in a word processor. You can't change the text, but you can move the caret with the keyboard to navigate the document and highlight text.

Shortcuts Developers Should Know

View the HTML source of the current page	Ctrl + U
Reload the page	F5
Reload the page and force the browser's cache to be ignored	Ctrl + F5
Display the error console	Ctrl + Shift + J

The Complete List

You can find the complete list of keyboard shortcuts at Mozilla's FireFox website: http://support.mozilla.com/en-US/kb/Keyboard+shortcuts

If you learn the FireFox keyboard shortcuts, and learn them well, you'll find your browser experience involves a lot less friction. Don't be surprised if you still reach for the mouse at first out of habit, but once you learn how to use the keyboard there's no going back.

Silverlight ListBox SelectedItem/SelectedIndex Visual State Bug Workaround

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Fri, 01 Aug 2008 07:19:00 -1100

There is a UI bug in Silverlight 2 Beta 2's ListBox that has become a problem for me recently: When you set the SelectedItem or SelectedIndex property to programatically alter the current selection, the internal state of the ListBox is correctly updated, but the visual representation is not. From the user's perspective, it appears that nothing has been selected. You can read more about this bug at Delay's Blog (make sure you scroll down to the section titled "ListBox Bugs").

Delay offers a workaround, but it suffers from a flaw that you don't want to use in production code: each time his workaround is executed, a new but identical event handler is assigned to the LayoutUpdated event so that the more the workaround is used the larger the event handler list grows and the more redundant code is executed each time. It's both a memory leak and a potential performance bottleneck. Delay himself acknowledges the problem in the comments of his blog. But his basic idea, which is all he was trying to share, is sound.

So here is an updated version of Delay's workaround which you should be able to use in production code. Rather than using extension methods which you must explicitly call each time you set SelectedItem or SelectedIndex, this version extends the ListBox class. You can use this class as a replacement for the Silverlight 2 Beta 2 ListBox and the UI will correctly update when you change SelectedItem or SelectedIndex.

using System;

namespace Cooper.Silverlight.Controls
{
    public class ListBox : System.Windows.Controls.ListBox
    {
        private bool _visualSelectionNeedsUpdating;
        private int _selectedIndex;

        public ListBox()
            : base()
        {
            LayoutUpdated += new EventHandler(ListBox_LayoutUpdated);
        }

        private void ListBox_LayoutUpdated(object sender, EventArgs e)
        {
            if (_visualSelectionNeedsUpdating)
            {
                //Toggle value to force change
                base.SelectedIndex = -1;
                base.SelectedIndex = _selectedIndex;
                
                VisualSelectionNeedsUpdating = false;
            }
        }

        private bool VisualSelectionNeedsUpdating
        {
            get
            {
                return _visualSelectionNeedsUpdating;
            }
            set
            {
                _visualSelectionNeedsUpdating = value;

                if (_visualSelectionNeedsUpdating)
                    _selectedIndex = SelectedIndex;
            }
        }
        
        public new int SelectedIndex
        {
            get
            {
                return base.SelectedIndex;
            }
            set
            {
                base.SelectedIndex = value;

                VisualSelectionNeedsUpdating = true;
            }
        }

        public new object SelectedItem
        {
            get
            {
                return base.SelectedItem;
            }
            set
            {
                base.SelectedItem = value;

                VisualSelectionNeedsUpdating = true;
            }
        }
    }
}

This solution does not address the ListBoxItem class's IsSelected property, but for my needs it is acceptable until RTM.

Thanks for showing us the way, Delay.

Snippets for Boilerplate Code When Overriding Equality and Hash Code

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Thu, 31 Jul 2008 12:33:41 -1100

Overriding Equals and GetHashCode is easy, but implementing them correctly is not. As Jonathan Allen says in his excellent article A Detailed look at Overriding the Equality Operator, "It is surprisingly easy to make a mistake when overriding the equality operator. Not only does the equality operator bring along with it a lot of baggage, there is a lot of flawed guidance out there, even on the MSDN website. So we are going to try to clear the air by presenting a systematic breakdown of both a reference type and a value type that supports equality." Jonathan then goes on to provide guidance and code examples when overriding Equals or GetHashCode in a class or struct.

Using Jonathan's code examples as a starting point, I've created a couple of Visual Studio snippets, one for class and one for struct, to blast out all of the boilerplate code associated with overriding equality and hash code, allowing you to focus on implementing what's important.

Here's a 30-second demo to show you what it does:

There are two snippets, one for class and one for struct, as outlined in Allen's original article. You can them here:

Equality and Hash Code Boilerplate Snippets for Class and Struct in C# (ZIP file)

Just unzip the file and use the Code Snippets Manager in Visual Studio to add these snippets to your environment (for Visual Studio 2008, click Tools... Code Snippets Manager... or Ctrl + K, Ctrl + B).

The Quest for Quick-and-Easy Immutable Value Objects in C#

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Tue, 03 Jun 2008 09:57:00 -1100

Definition of Terms

In the following discussion I will use the term Value Object to refer to an object which:

expresses only a value, or set of related values
has no identity
is typically immutable

This is a standard description of a Value Object as given by Domain Driven Design (see the Value Object definition at domaindrivendesign.org, or see Evans, Domain Driven Design p. 97ff; cf. Fowler, PoEAA, front cover and p. 486ff). I will use the term value type to refer to something more specific: any .NET type which derives from System.ValueType. In C#, this means structs, enums, and most of your built-in types (excluding string). A Value Object is a concept or pattern while a value type is a concrete part of the .NET framework. In .NET, a Value Object could be implemented using either a value type (struct) or a reference type (class).

Great, now on to the real stuff...

Aren't Structs Enough?

Martin Fowler in PoEAA has this to say about Value Objects in .NET:

.NET has a first-class treatment of Value Object. In C# an object is marked as a Value Object by declaring it as a struct instead as a class [sic]. The environment then treats it with value semantics.

While it's true that structs do offer built-in value-based equality and hash code, structs have some important limitations you should be aware of before you consider them the absolute solution for all your Value Object implementation needs:

Structs do not allow inheritance. If you need to create a new Value Object that extends some base object, structs won't allow you to do it. This is not an uncommon situation for me: I may have an Address Value Object that serves as a base international address, and then derive a country-specific address, such as USAddress, from it. I can't do this with structs.
Structs cannot guarantee construction to a valid state. Structs always include a default, parameterless constructor which initializes every field to its default value (such as null or 0). What this means is that, even if you provide a constructor that takes parameters to fully initialize all of the Value Object's internal fields, there is no guarantee that a caller won't bypass it and use the default constructor instead. Consider an Address Value Object implemented as a struct that expects it's fields to be populated before it can be used; there's nothing stopping someone from simply passing a new Address() to a method in your domain model that expects a correctly-initialized Address which then chokes on a bunch of null data.
Structs do not offer built-in immutability (and neither to classes). This really isn't a criticism of structs as much as a clarification of Mr. Fowler's advice. Usually, your Value Objects should be immutable. There are exceptions to this (see Evans, Domain Driven Design, p. 101, side column), but generally speaking you want immutability by default. For this reason, I don't consider a struct to be a "first-class treatment" of Value Object implementation. It's as close as you get, but just understand that if you want true immutability, you have to do all of the same grunt-work as you would with a class: readonly fields, get-only properties, and an appropriate constructor to initialize the object.

Luca Bolognese offers even more reasons why structs aren't the ideal solution for implementing Value Objects, but to me the lack of inheritance and construction are the two most significant.

Structs vs. Classes: Lots of Typing Either Way You Slice It

The truth is, neither structs nor classes offer quick-and-easy implementation of immutable Value Objects. They each have their own advantages and disadvantages, but they also both share some similar shortcomings that you'll have to face regardless of which one you use. To illustrate this, here is a comparison of structs and classes with regards to their suitability for Value Object implementation. I've colored aspects of each in red if it makes implementing a Value Object more difficult, and in green if it makes it easier:

struct	class
value type (stack)	reference type (heap)
cannot be null	can be null
does not allow inheritance	allows inheritance
always includes a default constructor	can require a specific constructor
automatic implementation of Equals and GetHashCode based on value	Equals and GetHashCode must be overridden for value-based equality
must override == and != operators	must override == and != operators
immutable properties require a lot of typing to implement: a private, readonly field a public get-only property a corresponding constructor for initialization	immutable properties require a lot of typing to implement: a private, readonly field a public get-only property a corresponding constructor for initialization

So if you use a struct, you gain automatic equality and hash code implementation (though it requires boxing), but you lose inheritance and absolute control of construction. If you use a class, you gain inheritance and and construction control, but then you're faced with having to manually implement value-based equality and hash code. But either way you go, there's a lot of repetitive typing required.

For example, let's say we wanted to define simple Value Object called PersonName that had two string properties: FirstName and LastName. A minimal class-based implementation in C# might look like this:

    
    public class PersonName
    {
        private readonly string _firstName;
        private readonly string _lastName;

        public PersonName(string firstName, string lastName)
        {
            _firstName = firstName;
            _lastName = lastName;
        }

        public string FirstName
        {
            get { return _firstName; }
        }

        public string LastName
        {
            get { return _lastName; }
        }

        public PersonName NewFirstName(string newFirstName)
        {
            return new PersonName(newFirstName, LastName);
        }

        public PersonName NewLastName(string newLastName)
        {
            return new PersonName(FirstName, newLastName);
        }

        #region Equality and Hash Code

        public override bool Equals(object obj)
        {
            var temp = obj as PersonName;

            if (!object.ReferenceEquals(temp, null))
                return this.Equals(temp);

            return false;
        }

        public static bool operator ==(PersonName left, PersonName right)
        {
            return object.Equals(left, right);
        }

        public static bool operator !=(PersonName left, PersonName right)
        {
            return !(left == right);
        }

        public bool Equals(PersonName other)
        {
            if (object.ReferenceEquals(other, null))
                return false;
            else if (object.ReferenceEquals(other, this))
                return true;

            return (this.FirstName == other.FirstName && this.LastName == other.LastName);
        }

        public override int GetHashCode()
        {
            int hashCode = 0;

            hashCode = (hashCode * 37) + (FirstName == null ? 0 : FirstName.GetHashCode());
            hashCode = (hashCode * 37) + (LastName == null ? 0 : LastName.GetHashCode());

            return hashCode;
        }

        #endregion
    }

A struct-based implementation (if we're comfortable with the nature of a struct) is a little better, but not much:

    
    public struct PersonName
    {
        private readonly string _firstName;
        private readonly string _lastName;

        public PersonName(string firstName, string lastName)
        {
            _firstName = firstName;
            _lastName = lastName;
        }

        public string FirstName
        {
            get { return _firstName; }
        }

        public string LastName
        {
            get { return _lastName; }
        }

        public PersonName NewFirstName(string newFirstName)
        {
            return new PersonName(newFirstName, LastName);
        }

        public PersonName NewLastName(string newLastName)
        {
            return new PersonName(FirstName, newLastName);
        }

        #region Equality Operators

        public static bool operator ==(PersonName left, PersonName right)
        {
            return object.Equals(left, right);
        }

        public static bool operator !=(PersonName left, PersonName right)
        {
            return !(left == right);
        }

        #endregion
    }

All of that just to get an immutable Value Object with two properties. Either way you go, class or struct, it's still a lot of noise.

So What Do We Need?

What we need is an easy way to quickly implement an immutable Value Object. We should simply have to specify the name of our Value Object, the names and types of each of its properties, and all of the boilerplate stuff should be done for us: equality, hash code, a standard constructor for our fields, and optionally some helper methods to create new value objects by specifying a new value for a property (like NewFirstName and NewLastName).

This is a simplification of the problem, though, because in practice there's a lot of little stuff that often needs tweaking. For example, you may need to tweak the Equals or GetHashCode method (say to ignore the case of some of your string-based properties), you may need to do something a lot more complex in your constructor than merely assign values to fields, or you may need to call a base constructor and pass in certain pre-defined values, etc. Ideally, we should have some way of specifying the basic outline of a value object--it's name and properties--have the boilerplate stuff generated for us, but still have the option of stepping in and hand-tuning anything that needs it.

Luca Bolognese's Approach

Luca Bolognese has blogged about much the same thing as I have above, and his quest for quick-and-easy immutable Value Objects in C# led him to creating a library of objects that model functional programming concepts which he borrowed from F#! I actually spent quite a bit of time with Luca's idea, but in the end decided that his library-approach didn't provide the level of fine-grained control I was after. Nevertheless, I learned a lot from Luca and came away with my own version of his library that I'll definitely be using in the future.

My Quest

I've spent a lot of time over the past month in pursuit of an easy way to implement Value Objects in C#. My quest for the Value Object Holy Grail has led me from snippets, to macros, to code generating classes configured by XML and harnessed by text templates in Visual Studio. I'll be blogging about each of them individually in future posts.

Suggestions for the C# Team

It would be nice if we had built-in language support for immutable Value Objects.

A step in the right direction would be to allow readonly as a modifier to property setters. With this, we could reduce the standard immutable property code to a simple public string FirstName { get; readonly set; }. While I've wanted this feature for a while, more is needed to complete the picture: we need the compiler to help us with equality and hash code support.

What if there were just one or two new keywords which we could use to designate to the C# compiler

that we want equality and hash code automatically implemented for a class, and
which fields/properties/methods should be used for the equality and hash code computation.

Perhaps something along the lines of:

    //The keyword "valueobject" indicates that Equals(object), Equals(PersonName), ==, !=, 
    //and GetHashCode should all be automatically generated by the compiler based on the use
    //of "valueitem" (see below).
    public valueobject class PersonName
    {
        //The keyword "valueitem" indicates that this property
        //should be used when calculating equality and hash code
        public valueitem string FirstName { get; readonly set; };

        //Here this property would *not* be considered for equality/hash code.
        //Instead, we'll use a custom, private property (below) so that our equality
        //and hash code use a modified version.
        public string LastName { get; readonly set; };

        //Constructor implementation is still done as usual to give us complete control.
        //Note, though, the use of the readonly property setters.
        public PersonName(string firstName, string lastName)
        {
            FirstName = firstName;
            LastName = lastName;
        }

        //Rather than use LastName directly, we instruct the compiler to use this property
        //as part of the equality/hash code computation, allowing us to ignore the case 
        //of the last name.
        private valueitem string LastNameValueItem { get { return LastName.ToLower(); } }
    }

Then, we could do something like this:

	PersonName adamCooper1 = new PersonName("Adam", "Cooper");
	PersonName adamCooper2 = new PersonName("Adam", "COOPER");
	PersonName johnDoe = new PersonName("John", "Doe");
	PersonName adamCooperIncorrectFirstNameCase = new PersonName("adam", "Cooper");

	//Writes "false" since these two objects clearly have different values
	Console.WriteLine(adamCooper1 == johnDoe);

	//Writes "true" since our object ignores last name case
	Console.WriteLine(adamCooper1 == adamCooper2);

	//Writes "false" since our object requires first names to be identical in case
	Console.WriteLine(adamCooper1 == adamCooperIncorrectFirstNameCase);

This is a short example, but you can easily see how powerful just a couple of new keywords and the ability to create readonly property setters would be. I'd love to hear what other folks think about this idea, both inside and outside Microsoft.

The most glaring problem I see is how to "automatically" implement GetHashCode, since the compiler would need to know how to combine a bunch of separate hash codes into a new hash code. I'll leave this to better minds to work out, but it would be nice if there was some way to specify how a class should concatenate two hash codes and have the compiler use that or default to a known-good implementation.

But whether the syntax looks like this or something completely different, it's hard to argue that built-in immutable Value Object support wouldn't be a good thing, particularly with the rise of distributed and parallel computing.

Relevant Resources

Jonathan Allen's "A Detailed look at Overriding the Equality Operator" - This is an excellent article demonstrating how to implement equality and hash code for both classes and structs in C#. If you need to implement Equals, ==, !=, or GetHashCode by hand and aren't sure what you're doing, make sure you read Jonathan's article first.
Luca Bolognese's Series on Creating Immutable Value Objects in C# - You'll want to find other resources for the specifics of implementing equality and hash code, but Luca's thoughts on the subject of Value Object implementation in C# are still relevant.
Luca Bolognese's Series on a C# Library to Write Functional Code - Luca's Value Object series above segued into a new series on functional objects in C# when he had the idea to use an immutable Record class as a base for his Value Objects.
- Part I - Background
- Part II - Tuples
- Part III - Records
- Part IV - Type Unions (planned)
- Part V - Match (planned)
Eric Evans, Domain Driven Design
Martin Fowler, Patterns of Enterprise Application Architecture

Microsoft's T4: A Free Alternative to CodeSmith

adam.nospam@nospam.adamjcooper.com (adamjcooper) — Tue, 03 Jun 2008 08:47:53 -1100

I've long been a fan of CodeSmith, an easy-to-use templating engine for creating code of any kind, though I've been a fan from the sidelines, never having purchased a license. My code generation needs are simply too infrequent to justify myself or my company purchasing a commercial code generator. As a result, I've resorted to creating ugly Console projects to generate code on the rare occasions I don't want to do it by hand.

Not anymore.

Microsoft has quietly included a new template-based code generation tool in Visual Studio 2008 called the Text Template Transformation Toolkit, a typical Microsoft-mouthful product name which is often shortened to T4. Officially part of Microsoft's DSL Tools project, T4 is actually a tool that any developer can leverage whether they're working with DSL tools or not. You won't find T4 advertised anywhere inside Visual Studio, but if you create a text file in your project with the extension ".tt" you'll see the T4 magic start to kick in: an associated code file is nested under the new ".tt" file, and Visual Studio understands the ".tt" file as an ASP.NET-like "text template" which it uses to generate the associated code file for your project. You can then develop repetitive code via the template, get feedback on whether the template compiles or not, and watch your associated code file become part of the build process.

Out-of-the-box editing of text templates is pretty poor though: there's no IntelliSense, and there's no syntax highlighting, which is most-likely why Microsoft has made this a "hidden" feature. The good news is there is a free T4 editor available from Clarius Consulting that eases some of the pain. Though it does not (yet) add IntelliSense support, it does add some much-needed code-block coloring so you can easily distinguish between what is template code and what is generated code. If you want to take T4 for a spin, do yourself a favor and go download the Claruis T4 Editor first.

Getting Started

Oleg Sych has written extensively about T4 and he has a great introductory article available on his blog:

http://www.olegsych.com/2007/12/text-template-transformation-toolkit/

If you want to learn about T4, Oleg's blog is one of the best places to go.

Limitations and Advice

Here are a few issues I've encountered when using text templates:

C# extension method syntax is not recognized. You can still call extension methods, but you will need to call them as a normal static method from the class in which they are defined. For example, if you have a class called StringExtensions that defines an extension method called TrimToNull(), instead of calling myString.TrimToNull(), you'll have to call the static method directly: StringExtensions.TrimToNull(myString).
Referencing your own assemblies to use within your template code takes just a little work. You either need to provide the full path to your assembly using a template assembly directive, or you need to add this path to your project's reference paths in the project properties dialog. Oleg explains more about this here: http://www.olegsych.com/2008/02/t4-assembly-directive/
Don't make your template code depend on the assembly it is generating code for. This type of circular dependency is just begging for trouble. I foolishly headed down this route since I was generating code for a commonly-used utility library and I wanted to leverage that same library in my templates. If you really need to use some functionality from the assembly you're generating code for in your templates, either refactor the assembly into separate assemblies so there is no more circular dependency or save a recent build of the assembly into a different location and use that build exclusively for your templates.
No IntelliSense. This is just part of life if you're going to use T4 right now. You can always keep an extra .cs or .vb file open for those times you want IntelliSense, and then copy and paste your code into the template. It's not the best, but it sure beats writing a Console project to generate code.

If Microsoft continues to improve T4 with a real editor that includes syntax highlighting, IntelliSense, and full support for C# and VB.NET language features such as extension methods, we'll have a real winner.