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

  • Article

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:

helloWorld

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:

bgColor

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:

qiProp

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:

infoBubbleBGDP

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:

infoBubbleDP

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

summary

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 =)