Luv the not control net updating user want this

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 (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, , 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 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 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 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 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 is most often set to a view model or business / model object, as in our case where the top level control, the , has its set to an instance of .

As a result, the for and all of its child elements is also . This is why our Value binding is failing. Value is a property of , not our model object.

So how do we go about fixing this? Most people's first reaction is to set the 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!

With the of the control now set to itself, our label is now working:

However, now our value has disappeared! Again, this is a issue, the binding in our user control is on a property, whilst the is now the instance.

This is not such a big problem, we were going to have to change that anyway, a hard-coded binding to the 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 dependency property, we now add a property:

This value property is bound to the user control UI as follows:

The idea here is that the exposed property 'relays' the value of the binding in our, 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 to itself is a mistake? We have just found out why!

The source of a binding is the of the control it is defined upon. In our we have attempted to bind the property of the to the property on our model object. However, the code within the constructor means that it no longer inherits its parent's (i.e. our model object), so this binding does not work.

This problem can be fixed by setting the of the '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 to itself.

This means that the still inherits its parent's , so bindings to our model object will work. Furthermore, the and its children all have the as their , 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 of is inherited from its parent. This means that any bindings we add to have the as their source.

We can now create multiple instances of to edit different properties:

With an update of the 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 without any code-behind by using an binding as follows:

Or, in WPF you could event use a binding, with set to the type of (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:

Regards, Colin E.