Using Design-Time Attributes to Categorize Dependency Properties in User Controls

In most cases, when you create user or custom controls, you will expose dependency properties to allow you to set values or make modifications to your control directly via XAML. Because XAML is the language of Blend, Blend will expose those dependency properties in the property grid itself. For example, let's say you have a user control that displays information in a colored box:

This user control has two dependency properties. The first property is called QuickInfo that displays some text such as "Hello World!", and it returns a value of type String. The second property is called BackgroundColor, and as its name implies, sets the background color of our user control. As you may guess, the BackgroundColor property returns a value of type Brush.

Default Behavior
In Blend, if you select a user control on the design surface, by default, any dependency properties you expose are displayed in the property grid. Blend looks at the return type of each dependency property and categorizes it in the appropriate location accordingly.

For example, our BackgroundColor dependency property will find its way into the Brushes panel because it returns a value of type Brush:

Our QuickInfo dependency property isn't quite as lucky. Because QuickInfo simply returns a string, Blend doesn't know exactly where to place it. Any dependency properties you create that can't be easily categorized are placed in the Miscellaneous panel:

For just two dependency properties, the default behavior may be fine. If your user control has a lot of dependency properties or someone other than yourself will be using this user control, then you should look into categorizing them.

Using Design-Time Attributes
To help design tools such as Blend and Visual Studio, the .NET Framework allows you to use design-time attributes. The following MSDN article (https://msdn2.microsoft.com/en-us/library/tk67c2t8.aspx) goes into greater detail, but in a nutshell, you can specify the category and a description for your dependency property. Blend will take care of the rest.

The general format for a design-time attribute is [Category("Value"), Description("Value")]

In your  user control's code-behind file, in Visual Studio, find the locations where you declare the CRL wrappers for your dependency properties. Above the declaration, add your design-time attribute. For example, the following is what I declared above my BackgroundColor wrapper:

I do something similar for my QuickInfo dependency property also. Once you have provided the category/description for each dependency property you are interested in, go back to Blend, rebuild your project, and select the user control whose code you modified in Visual Studio. Look in your property grid. At the very bottom, you will see your custom categories and properties that fall under them.

In my case, I categorized both of my dependency properties into InfoBubble:

If you hover over each dependency property's name, the description value you provided will display:

Conclusion
As you can see, by using design-time attributes, you have some flexibility over how Blend will behave when faced with a dependency property that it doesn't know how to categorize. Beyond design-time attributes, there are many other classes of attributes that various developments tools such as Blend and Visual Studio listen for, so be sure to look into them and see if they can help you out.

Cheers!
Kirupa =)

Comments

• Anonymous
  January 13, 2008
  PingBack from http://msdnrss.thecoderblogs.com/2008/01/13/using-design-time-attributes-to-categorize-dependency-properties-in-user-controls/

• Anonymous
  January 13, 2008
  In most cases, when you create user or custom controls, you will expose dependency properties to allow

• Anonymous
  January 13, 2008
  In most cases, when you create user or custom controls, you will expose dependency properties to allow

• Anonymous
  February 06, 2008
  In most cases, when you create user or custom controls, you will expose dependency properties to allow

• Anonymous
  February 17, 2008
  Following the post I get this: The type or namespace name 'Category' could not be found (are you missing a using directive or an assembly reference?) This leads me to believe that I'm probably missing a reference to System.Design or something similar when working with a Silverlight project.  When trying to add a reference System.Design isn't available.  Great...

• Anonymous
  August 31, 2009
  Kirupa, I use these Design-Time Attributes for exposing properties in Blend. But in the following scenario I have used 2 properties; DisplayedStartDate & DisplayedEndDate. But because the "E" is before the "S", Blend displayes DisplayedStartDate after DisplayedEndDate. Is there a way I can change the display order of the properties (So DisplayedStartDate is displayed before DisplayedEndDate)? Many thankx!

• Anonymous
  December 15, 2009
  Thx Kirupa! <3 Willie: using System.ComponentModel; or [System.ComponentModel.Category("Willie Tilton")] :)