Custom classes that are used in XAML can be defined in two distinct ways: within the code-behind or other code that produces the primary Windows Presentation Foundation (WPF) application, or as a class in a separate assembly, such as an executable or DLL used as a class library. Each of these approaches has particular advantages and disadvantages.

• The advantage of creating a class library is that any such custom classes can be shared across many different possible applications. A separate library also makes versioning issues of applications easier to control, and simplifies creating a class that you intend to use as a root element on a XAML page.

• The advantage of defining the custom classes in the application is that this technique is relatively lightweight and minimizes the deployment and testing issues encountered when you introduce separate assemblies beyond the main executable. However, one notable disadvantage is that you cannot use classes defined in the same assembly as the root element of a XAML page.

• Whether defined in the same or different assembly, custom classes need to be mapped between CLR namespace and XML namespace in order to be used in XAML as elements. See XAML Namespaces and Namespace Mapping.

In order to be able to be instantiated as an object element, your class must meet the following requirements:

• Your custom class must be public and support a default (parameterless) public constructor. (Managed-code structures implicitly support such a constructor.)

• Your custom class must not be a nested class (nested classes and the "dot" in their syntax interfere with other WPF features such as attached properties).

In addition to enabling object element syntax, you also enable property element syntax for any other public properties that take that object as their value type. This is because the object can now be instantiated as an object element and can fill the property element value of such a property.

Structures

Properties must reference a by-value type (such as a primitive), or use a class for type that has either a default constructor or a dedicated type converter at the class level.

Alternatively, the property may reference an abstract class type, or an interface. For abstract classes or interfaces, the expectation at run time is that the property value must be filled with practical class instances that implement the interface, or class instances that derive from the abstract class.

Properties can be declared on an abstract class, but can only be set on practical classes that derive from the abstract class, because creating the object element for the class at all requires a public default constructor on the class.

Type-converter Enabled Attribute Syntax

<Button>Hallo!
  <Button.Language>
    de-DE
  </Button.Language>
</Button>

<Button Language="de-DE">Hallo!</Button>

Per-Property Type Converters

Writing and Attributing a Type Converter

To be usable as a CLR event, the event must be exposed as a public event on a class that supports a default constructor, or on an abstract class where the event can be accessed on derived classes. In order to be used conveniently as a routed event, your CLR event should implement explicit add and remove methods, which add and remove handlers for the CLR event signature and forward those handlers to the AddHandler and RemoveHandler methods. These methods add or remove the handlers to the routed event handler store on the instance that the event is attached to.

Note:
It is possible to register handlers directly for routed events using AddHandler, and to deliberately not define a CLR event that exposes the routed event. This is not generally recommended because the event will not enable XAML attribute syntax for attaching handlers, and your resulting class will offer a less transparent XAML view of the class object model.

Properties that take a collection type have a XAML syntax that enables you to specify objects that are added to the collection. This syntax has two notable features.

• The object that is the collection object does not need to be specified in object element syntax. The presence of that collection type is implicit whenever you specify a property in XAML that takes a collection type.

• Child elements of the collection property are processed to become members of the collection. Ordinarily, the code access to the members of a collection is performed through collection methods such as Add, or through a collection indexer property. But XAML syntax does not support methods or indexers. Collections are obviously a very common requirement for building a tree of elements, and you need some way to populate these collections in declarative XAML. Therefore, child elements of a collection property are processed by adding them to the collection that is the collection property type value.

The WPF XAML processor uses the following definition for what constitutes a collection property. The property type of the property must implement one of the following:

• Implements IList.

• Implements IDictionary or the generic equivalent (IDictionary<(Of <(TKey, TValue>)>)).

• Derives from Array (for more information about arrays in XAML, see x:Array Markup Extension.)

• Implements IAddChild (an interface defined by WPF).

Each of these types has an Add method, which is used by the XAML processor to add items to the underlying collection.

Note:
The generic List and Dictionary interfaces (IList<(Of <(T>)>) and IDictionary<(Of <(TKey, TValue>)>)) are not supported for collection detection by the WPF XAML processor. However, you can use the List<(Of <(T>)>) class as a base class, because it implements IList directly, or Dictionary<(Of <(TKey, TValue>)>) as a base class, because it implements IDictionary directly.

When you declare a property that takes a collection, be cautious about how that property value is initialized in new instances of the type. If you are not implementing the property as a dependency property, then having the property use a backing field that calls the collection type constructor is adequate. If your property is a dependency property, then you may need to initialize the collection property as part of the default type constructor. This is because a dependency property takes its default value from metadata, and you typically do not want the initial value of a collection property to be a static, shared collection (there should be a collection instance per each containing type instance). For more information, see Custom Dependency Properties.

You can implement a custom collection type for your collection property. Because of implicit collection property treatment, the custom collection type does not need to provide a default constructor in order to be used in XAML implicitly. However, you can optionally provide a default constructor for the collection type. This can be a worthwhile practice, because unless you do provide a default constructor, you cannot explicitly declare the collection as an object element. Some markup authors might prefer to see the explicit collection as a matter of markup style. Also, a default constructor can simplify the initialization requirements when you create new objects that use your collection type as a property value.

The XAML language defines the concept of a XAML content property. Each class that is usable in object syntax can have exactly one XAML content property. To declare a property to be the XAML content property for your class, apply the ContentPropertyAttribute as part of the class definition. Specify the name of the intended XAML content property as the Name in the attribute.

You can specify a collection property to be the XAML content property. This results in a usage for that property whereby the object element can have one or more child elements, without any intervening collection object elements or property element tags. These elements are then treated as the value for the XAML content property and added to the backing collection instance.

Some existing WPF XAML content properties use the property type of Object. This enables a XAML content property that can take primitive values such as a String as well as taking a single reference object value. If you follow this model, your type is responsible for type determination as well as the handling of possible types. The typical reason for an Object type model is to support both a simple means of adding object content as a string (which receives a default presentation treatment), or an advanced means of adding object content that specifies a non-default presentation.

For certain scenarios, such as if you are a control author, you may also want to assure that any object representation that can be instantiated in XAML can also be serialized back to equivalent XAML. Serialization requirements are not described in this topic. See Control Authoring Overview and Element Tree and Serialization.

Concepts