198

I am just coming up to speed on WPF and would like to create a reusable WPF control.

When I look at the options for creating projects in Visual Studio, I see "WPF User Control Library" and "WPF Custom Control Library". It's unclear to me what the difference is between them and my Google searches have not turned up any decent explanations.

I'd like to understand the differences between them and ideally see some examples of when to use one over the other.

Lightness Races in Orbit
  • 378,754
  • 76
  • 643
  • 1,055
17 of 26
  • 27,121
  • 13
  • 66
  • 85
  • 2
    Don't forget nesting content or changing a control's template as options. You can make pretty dramatic changes to a control this way without having to write a custom control. – MichaC Apr 30 '09 at 16:41
  • Just what MichaC said. The best part of WPF is that templating existing controls can have a huge impact. You should require custom controls rarely. This is unlike to WinForms where even minor changes to a control required a new derived control. – Mikko Rantanen Apr 30 '09 at 16:47
  • Still useful. Have another gold badge. – ouflak Mar 03 '16 at 10:56

3 Answers3

131

In practice custom controls are something you implement on the code level while you can use XAML for user controls. The custom controls extend one of the WPF control base classes and provide additional functionality through code so all the added logic and representation must be implemented inside the code.

A user control is technically a normal content control which you can extend in some parts in the code but usually it is extended by placing other controls inside it. So as Kent mentioned a UserControl is an aggregation of other controls. This limits what you can do with a user control considerably. It's easier to use but more limited than a full custom control.

These controls have a small difference from a runtime point of view. When building an application and placing an UserControl into it, the control tree will have a concrete UserControl template inside of it. So if we consider a lame example of a specialized button. If you were using a user control you'd add a button inside the <UserControl> element. When using a custom control you'd derive the control itself from a button most likely. The difference would be visible in the logical tree.

While the custom control would provide a logical tree similar to

  • Window
    • CustomButton

The UserControl would give a logical tree of

  • Window
    • CustomButtonUserControl
      • Button

So in the end the UserControl is just a normal ContentControl which you can extend a bit and for which you can predefine the content. Custom control provides greater flexibility at the price of ease of implementation as you have to do all the logic and interaction in the code instead of having the benefit of XAML.

Though after all this, I don't think there's that much difference in the Visual Studio templates. Most likely the Visual Studio Custom Control just creates a project with an empty custom control while the User Control project is a project with an empty user control. You can later add any kind of items to the project.

Update

And my opinion on when to use custom control and user control is that if you can get something done with a user control and the extra control element in the logical tree doesn't bother you, use a user control as they are so much easier to create and maintain. Use a custom control only if you have a reason not to use a user control.

Mikko Rantanen
  • 7,884
  • 2
  • 32
  • 47
  • 2
    Can a custom control be used to aggregate other controls? – 17 of 26 Apr 30 '09 at 16:31
  • And what about the skinnable/templatable issue? – 17 of 26 Apr 30 '09 at 16:33
  • 1
    Not sure what you mean by aggregating. You cannot create a Custom Control by aggregating other controls. You can however derive from a Panel control such as StackPanel, Grid or Panel itself so you can implement a layout container with a custom control (Not sure if you can do that with a User Control). – Mikko Rantanen Apr 30 '09 at 16:35
  • Yes, but if you just want to aggregate other controls it would probably be much easier to do with a User Control. Depending on what you want to do a custom control can be really hard to write, which is why you would choose to use a User Control even though it only provides a subset of the capabilities. – MichaC Apr 30 '09 at 16:37
  • 1
    Both of these controls should be skinnable/templatable when implemented the correct way. Unfortunately my WPF reference is at the office currently so I can't check the implementation details. – Mikko Rantanen Apr 30 '09 at 16:37
  • I had to downvote, signal:noise very low compared to Kent's answer to such a basic question. – yzorg Feb 20 '11 at 05:27
  • This answer seems to me to be missing something. You can inherit from other controls and use XAML, by having the root element of the XAML document be another control. – Zev Spitz Aug 29 '19 at 21:19
25

A Control represents some behavior that is skinnable (templatable), whereas a UserControl is generally a higher-level aggregation of Controls that is specific to an application.

More info available here.

Kent Boogaart
  • 175,602
  • 35
  • 392
  • 393
  • 3
    That's one of the links I found that didn't explain things very well :). I guess one thing I'm missing is what skinnable/templatable really means and why it can't be done with a user control. Also, the last sentence of the linked post is "Generally & Simply speaking, custom controls have better flexibility and reusability than user controls". If that is true, then why would I ever want to create a user control? – 17 of 26 Apr 30 '09 at 16:19
6

Difference between User Control Library, Custom Control Library, and WPF Class Library Templates

To answer the original question the primary difference between the two library templates, is that one comes with a default empty user control, and the other comes with a default empty custom control. They are both WPF class libraries. Either project can contain zero or more user controls and zero or more custom controls.

In addition, as explained in separate posts by Novitchi S and Cameron Macfarland the custom control library also adds a ThemeInfo assembly attribute to resolve the location of default Styles/Templates for the control.

Difference between User Controls and Custom Controls

A user control is an aggregate of WPF controls (including other user controls) whereas a custom control is a class derived from Control.

This MSDN article makes the following recommendations about when to choose between developing a user control, a custom control, or deriving from framework element.

Consider deriving from UserControl if all of the following apply:

  • You want to build your control similarly to how you build an application.
  • Your control consists only of existing components.
  • You don't need to support complex customization.

Consider deriving from Control if any of the following apply:

  • You want the appearance of your control to be customizable via the ControlTemplate.
  • You want your control to support different themes.

Consider deriving from FrameworkElement if any of the following apply:

  • You want to have precise control over the appearance of your control beyond what is provided by simple element composition.
  • You want to define the appearance of your control by defining your own render logic.

Other good advice from other StackOverflow answers:

Reed Copsey explains "UserControls are meant to compose multiple WPF controls together, in order to make a set of functionality built out of other controls" and further goes on to share his experience that "the need for CustomControls is actually fairly rare in WPF, since the WPF templating options and attached properties allow you to do nearly anything with standard controls".

Mikko Rantanen similarly shares their opinion "use custom control and user control is that if you can get something done with a user control and the extra control element in the logical tree doesn't bother you, use a user control as they are so much easier to create and maintain."

cdiggins
  • 17,602
  • 7
  • 105
  • 102