This blog post provides step-by-step instructions for creating a user control, which exposes bindable properties, in WPF and Silverlight. The post covers dependency properties, and how to manage DataContext inheritance.
When building user interfaces you will often find yourself repeating the same UI patterns across your application. After all, users like to be presented with a consistent interface, so re-use makes sense. The WPF and Silverlight frameworks provide custom controls and user controls as a mechanism for re-using blocks of UI elements. Custom controls are rather special, with the logic being de-coupled from the XAML in order to support templating. For most needs, the simpler user control is more appropriate.
From participating in sites like StackOverflow I have noticed that whilst most people understand how to create a user control, which allows them to 'stamp out' the same XAML in multiple places, many struggle with how to make their user controls flexible by exposing properties that configure how it looks or behaves. This blog post will walk through a simple example, showing you how to create a user control, add dependency properties, wire them to the user control XAML and make a truly re-useable control.
We'll start with a very simple example, an application that displays a simple form field which consists of a name and a value:
This UI is bound to a simple model object that implements
INotifyPropertyChanged (not shown for the sake of brevity):
The constructor instantiates the model object and sets it as the DataContext:
This produces the expected behaviour, a label and a text field that allows you to edit the Shoesize property:
Let's say we want to allow the user to edit the Height property as well. We could cut and paste our current XAML, but this will only cause maintenance issues in future. Instead, the preferred approach would be to move the XAML into a user control, allowing it to be re-used.
The first step is to create a new user control,
FieldUserControl, and move our XAML into there:
We can now replace the XAML we have moved with an instance of this user control:
Compiling and running this code proves that this still works; we can see the model property and edit it:
For trivial user controls this is all we need to do. However, in most cases, like this one, you will find that there are some elements of your user control that you wish to configure. In order to use this control for editing the
Height property we need to make the label configurable. We do this by adding a Label property to our
This is where things get a bit tricky! Ideally this property should support binding, just like any other property of the framework UI controls. The WPF / Silverlight binding framework revolves around the concept of dependency properties, you can make any property the source of a binding, but the target must be a dependency property (DP). So let's go ahead and add a
Label dependency property to our user control:
A lot of code isn't it? It's all boiler-plate stuff, you just have to live with it (I'd recommend either using code-snippets, or code generation for DPs)
We can now go ahead and bind the label text to this property:
However, if you compile and run the above code, you'll find that it doesn't work. The model property value is still displayed but the label is not.
So why is this?
Bindings have both a source and a target; where the binding framework is responsible for handling change notifications from the source and (optionally) the target, keeping the two synchronized. The bindings in our
FieldUserControl have a value for the Path, which specifies the target, but what is the source?
If you create a binding in XAML but do not specify the source (which is probably the most common use case), the source will be set to the
DataContext of the control the binding has been specified on. The DataContext is inherited down the visual tree, from each control's parent to child. The
DataContext is most often set to a view model or business / model object, as in our case where the top level control, the
MainPage, has its
DataContext set to an instance of
As a result, the
FieldUserControl and all of its child elements is also
ModelObject. This is why our Value binding is failing. Value is a property of
FieldUserControl, not our model object.
So how do we go about fixing this? Most people's first reaction is to set the
DataContext of the user control to itself (I distinctly recall doing this myself the first time I encountered this problem!). We'll find out later that this is a mistake - but for now let's just go with it!
DataContext of the control now set to itself, our label is now working:
However, now our value has disappeared! Again, this is a
DataContext issue, the binding in our user control is on a
Shoesize property, whilst the
DataContext is now the
This is not such a big problem, we were going to have to change that anyway, a hard-coded binding to the
Shoesize property means that we cannot re-use this control to edit other properties of the model object.
So we add another dependency property to our user control. We already have the
Label dependency property, we now add a
This value property is bound to the user control UI as follows:
The idea here is that the exposed
Value property 'relays' the value of the binding in our
MainPage.xaml, which now has a binding which tells us which model object property is being displayed in our user control:
If you compile and run this code you will find that ... it doesn't work!
Remember earlier when I said that setting the user control's
DataContext to itself is a mistake? We have just found out why!
The source of a binding is the
DataContext of the control it is defined upon. In our
MainPage.xaml we have attempted to bind the
Value property of the
FieldUserControl to the
Height property on our model object. However, the code within the
FieldUserControl constructor means that it no longer inherits its parent's
DataContext (i.e. our model object), so this binding does not work.
This problem can be fixed by setting the
DataContext of the
FieldUserControl's root element to itself.
Note that the user control has a StackPanel as its root element and that this is named
We change the constructor so that it sets the
DataContext to itself.
This means that the
FieldUserControl still inherits its parent's
DataContext, so bindings to our model object will work. Furthermore, the
FieldUserControl and its children all have the
FieldUserControl as their
DataContext, so their bindings work also:
Finally, we're done!
If the technique of binding the layout root of the user control to itself is a bit confusing - the following diagram, which shows the visual tree of our simple application, might help:
Again, notice that the
FieldUserControl is inherited from its parent. This means that any bindings we add to
FieldUserControl have the
ModelObect as their source.
We can now create multiple instances of
FieldUserControl to edit different properties:
With an update of the
FieldUserControl styling, the result looks like this:
We now have a truly re-useable user control!
As an aside, for bonus points, you can bind the layout root
DataContext without any code-behind by using an
ElementName binding as follows:
Or, in WPF you could event use a
RelativeSource FindAncestor binding, with
AncestorType set to the type of
FieldUserControl (but that would just be showing off!).
Hopefully this blog post will help anyone who is confused about how to create user controls which expose properties in WPF or Silverlight.
You can download the sourcecode for the example: UserControlExample.zip
Regards, Colin E.