This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Silverlight classes, and have read Dependency Properties Overview. To follow the examples in this topic, you should also understand XAML and know how to write Silverlight-based applications.

One scenario for the creation of an attached property is to allow an object to specify unique values for a property that is actually defined in a different class object model, and is read at run time by the defining class once the various objects are created in relationships in an object tree. A specific application of this scenario is having child elements inform the parent element of how they are to be presented in the UI. One example is the Canvas..::.Left attached property. The Canvas..::.Left property is created as an attached property because it is designed to be set on elements that are contained within a System.Windows.Controls..::.Canvas, rather than on System.Windows.Controls..::.Canvas itself. The System.Windows.Controls..::.Canvas class defines the static DependencyProperty field named Canvas..::.LeftProperty, and then provides the SetLeft and GetLeft methods as public accessors for the attached property to enable both XAML setting and run-time value access.

In XAML, you set attached properties by using the syntax AttachedPropertyProvider.PropertyName

The following is an example of how you can set Canvas..::.Left in XAML:

    <Canvas>
      <Button Canvas.Left="50"><TextBlock>Hello</TextBlock></Button>
    </Canvas>

Note that the usage is somewhat similar to a static property; you always reference the type Canvas that owns and registers the attached property, rather than referring to any instance specified by name.

Also, because an attached property in XAML is an attribute that you set in markup, only the set operation has any immediate relevance to user code. The get operation is available to user code, but is really mainly used by the implementation of the class that defines the attached property.

Although attached properties are settable on any object, that does not automatically mean that setting the property will produce a tangible result, or that the value will ever be used by another object. Generally, attached properties are intended so that objects coming from a wide variety of possible class hierarchies or logical relationships can each report common information to the owning type. The type that defines the attached property for Silverlight typically follows one of these models:

• The type that defines the attached property is designed so that it can be the parent element of the elements that will set values for the attached property. The type then iterates its child elements through internal logic, obtains the values, and acts on those values in some manner.

• The type that defines the attached property will be used as the child element for a variety of possible parent elements and content models.

• The attached property reports information to a service.

Attached properties do not have the typical CLR wrapper methods for easy get/set access like other dependency properties do. This is because the attached property is not necessarily part of the CLR namespace for instances where the property is set. (It is permissible though uncommon to define a property that is both an attached property that other types can set on themselves, and also has a conventional property usage on the owning type.) A XAML processor must be able to set those values when XAML is parsed into an object tree. The owner type of the attached property must implement dedicated accessor methods in the form GetPropertyName and SetPropertyName. These dedicated accessor methods are also how you must get or set the attached property in code. From a code perspective, an attached property is similar to a backing field that has method accessors instead of property accessors, and that backing field can exist on any object rather than needing to be specifically defined.

The following example shows how you can set an attached property in code. In this example, myCheckBox is an instance of the CheckBox class.

    Canvas myC = new Canvas();
    CheckBox myCheckBox = new CheckBox();
    myCheckBox.Content = "Hello";
    myC.Children.Add(myCheckBox);
    Canvas.SetTop(myCheckBox, 75);

    Dim myC As Canvas = New Canvas()
    Dim myCheckBox As CheckBox= New CheckBox()
    myCheckBox.Content = "Hello"
    myC.Children.Add(myCheckBox)
    Canvas.SetTop(myCheckBox, 75)

Similar to the XAML setting example, if myCheckBox had not already been added as a child element of myC by the third line of code, the fourth line of code would not raise an exception, but the property value would not interact with a Canvas parent and thus would do nothing. Only a Canvas..::.Top value set on a child element combined with the presence of a Canvas parent element will cause an effective behavior in the rendered application.

How to define custom attached properties, and more about the scenarios for using an attached property, is documented in Custom Attached Properties.

Concepts