What is the difference between a User Control Library and a Custom Control Library?

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.

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.

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.

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."