BizTalk Custom Pipelines Components – Best Practices – Defining Design-Time Properties: Description and DisplayName

Unfortunately, in most of the examples of custom pipelines components, we many times forgot to customize properly the description and the display name of the properties of the pipeline component (myself including 🙂 ).

Normally we use BizTalk Server Pipeline Component Wizard to create the custom pipeline component that generates the following code:

private string _ArchiveFilename;
public string ArchiveFilename
{
   get
   {
      return _ArchiveFilename;
   }
   set
   {
      _ArchiveFilename = value;
   }
}

When we add the component to the pipeline, there was no description of the properties at the bottom of the property window, it appears like this:

Properties are easy enough to add programmatically, that would integrate perfectly into C# code. But In order to have really good components, it should be easily editable during the graphic design.

This lack of percussion cause some problem when the administrator or some other person tries to configure the component because he doesn’t know exactly what the properties refer to, he only has the name of the property to understand what this is for, in some cases is insufficient.

Customizing the Designer

To customize how the property is displayed by the designer you need four basic attributes: Description, DefaultValue, Browsable.

• Description – This is the description that the programmer sees at the very bottom of the Properties Window.
• DefaultValue – Specifies the default value of the property when the user control is first created.
• Browsable – If set to false, the property won’t be displayed at all in the designer. This attribute is useful if your property is to be modified only programmatically.

The Format

[properties go here]
public int MyProperty
{
   ...
}

So, to customize better the properties of the component, we have to set the:

• System.ComponentModel.DescriptionAttribute: Specifies a description for a property or event.
• System.ComponentModel.DisplayNameAttribute: Specifies the display name for a property, event, or public void method which takes no arguments.

Like this:

[Description("The filename of the archive message. This property can include macros")]
[DisplayName("Archive Filename")]
public string ArchiveFilename
{
   …
}

The differences in the result when we add the component to the pipeline are:

• We have a description of what the property refers to;
• We can define better the display name of the property, with spaces and special chars

Design-Time Property Browser Attributes

Design-time attributes are essential for displaying your control and its members correctly at design time, as they provide valuable information to a visual design tool.

In the following code fragment, the CategoryAttribute attribute enables the property browser to display the TextAlignment property in the Alignment category. The DescriptionAttribute attribute allows the property browser to provide a brief description of the property when a user clicks on it.

Attribute	Description
BrowsableAttribute	Determines whether the property is visible in the Property Browser. [Browsable(true)]
DescriptionAttribute	Defines a small block of text to be displayed at the bottom of the property browser when the user selects a property or event. [Description(“The color used for painting alert text.”)]
DefaultValueAttribute	Specifies the default value for a property. [DefaultValue(typeof(Color), “White”)]
ReadOnlyAttribute	Specifies that this property cannot be edited in the Property Browser. [ReadOnly(true)]
CategoryAttribute	Tells the Property Browser which group to include this property in. [Category(“Appearance”)]   Not Supported in pipeline components

See more in Common Attributes for Properties and Events or in System.ComponentModel