Framework property metadata (WPF .NET)
You can set framework property metadata options for dependency properties at the Windows Presentation Foundation (WPF) framework level. The WPF framework level designation applies when WPF presentation APIs and executables handle rendering and data binding. Presentation APIs and executables query the FrameworkPropertyMetadata of a dependency property.
The Desktop Guide documentation for .NET 6 and .NET 5 (including .NET Core 3.1) is under construction.
The article assumes a basic knowledge of dependency properties, and that you've read Dependency properties overview. To follow the examples in this article, it helps if you're familiar with Extensible Application Markup Language (XAML) and know how to write WPF applications.
Framework property metadata categories
FrameworkPropertyMetadata falls into these categories:
Metadata that affects the layout of an element, specifically the AffectsArrange, AffectsMeasure, and AffectsRender metadata flags. You might set those flags if your dependency property implementation affects a visual aspect and you're implementing MeasureOverride or ArrangeOverride in your class. The
ArrangeOverridemethods provide implementation-specific behavior and rendering information to the layout system. When
AffectsRenderare set to
truein the metadata of a dependency property and its effective value changes, the WPF property system will initiate a request to invalidate the element's visuals to trigger a redraw.
Metadata that affects the layout of the parent element of an element, specifically the AffectsParentArrange and AffectsParentMeasure metadata flags. Examples of WPF dependency properties that set these flags are FixedPage.Left and Paragraph.KeepWithNext.
Property value inheritance metadata, specifically the Inherits and OverridesInheritanceBehavior metadata flags. By default, dependency properties don't inherit values. OverridesInheritanceBehavior allows the pathway of inheritance to also travel into a visual tree, which is necessary for some control compositing scenarios. For more information, see Property value inheritance.
The term "inherits" in the context of property values is specific to dependency properties, and doesn't directly relate to managed code types and member inheritance through derived types. In the context of dependency properties, it means that child elements can inherit dependency property values from parent elements.
Data binding metadata, specifically the BindsTwoWayByDefault and IsNotDataBindable metadata flags. By default, dependency properties in the WPF framework support one-way binding. Consider setting two-way binding as the default for properties that report state and are modifiable by user action, for example IsSelected. Also, consider setting two-way binding as the default when users of a control expect a property to implement it, for example TextBox.Text.
BindsTwoWayByDefaultonly affects the default binding mode. To edit the data flow direction of a binding, set Binding.Mode. You can use
IsNotDataBindableto disable data binding when there's no use case for it. For more information on data bindings, see Data binding overview.
Journaling metadata, specifically the Journal metadata flag. The default value of the
Journalflag is only
truefor a some dependency properties, such as SelectedIndex. User input controls should set the
Journalflag for properties whose values hold user selections that need to be stored. The
Journalflag is read by applications or services that support journaling, including WPF journaling services. For information on storing navigation steps, see Navigation overview.
To retrieve metadata for a dependency property, call GetMetadata on the DependencyProperty identifier. The
GetMetadata call returns a
PropertyMetadata object. If you need to query framework metadata values cast
PropertyMetadata to FrameworkPropertyMetadata.
When you register a dependency property, you have the option to create and assign metadata to it. The metadata object that you assign can be PropertyMetadata or one of its derived classes, like FrameworkPropertyMetadata. Choose
FrameworkPropertyMetadata for dependency properties that rely on WPF presentation APIs and executables for rendering and data binding. A more advanced option is to derive from
FrameworkPropertyMetadata to create a custom metadata reporting class with more flags. Or, you might use UIPropertyMetadata for non-framework properties that affect UI rendering.
Although metadata options are typically set during registration of a new dependency property, you can respecify them in OverrideMetadata or AddOwner calls. When overriding metadata, always override with the same metadata type that was used during property registration.
The property characteristics that are exposed by
FrameworkPropertyMetadata are sometimes referred to as flags. If you're creating a
FrameworkPropertyMetadata instance, there are two ways to populate flag values:
Set the flags on an instance of the FrameworkPropertyMetadataOptions enumeration type.
FrameworkPropertyMetadataOptionslets you specify metadata flags in bitwise OR combination. Then, instantiate
FrameworkPropertyMetadatausing a constructor that has a
FrameworkPropertyMetadataOptionsparameter, and pass in your
FrameworkPropertyMetadataOptionsinstance. To change metadata flags after passing
FrameworkPropertyMetadataOptionsinto the FrameworkPropertyMetadata constructor, change the corresponding property on the new
FrameworkPropertyMetadatainstance. For example, if you set the FrameworkPropertyMetadataOptions.NotDataBindable flag, you can undo that by setting FrameworkPropertyMetadata.IsNotDataBindable to
FrameworkPropertyMetadatausing a constructor that doesn't have a
FrameworkPropertyMetadataOptionsparameter, and then set the applicable Boolean flags on
FrameworkPropertyMetadata. Set flag values before associating your
FrameworkPropertyMetadatainstance with a dependency property, otherwise you'll get an InvalidOperationException.
Metadata override behavior
When you override framework property metadata, changed metadata values either replace or are merged with the original values:
For a PropertyChangedCallback, the default merge logic retains previous
PropertyChangedCallbackvalues in a table, and all are invoked on a property change. The callback order is determined by class depth, where a callback registered by the base class in the hierarchy would run first. Inherited callbacks run only once, and are owned by the class that added them into metadata.
For a DefaultValue, the new value will replace the existing default value. If you don't specify a
DefaultValuein the override metadata and if the existing FrameworkPropertyMetadata has the
Inheritsflag set, then the default value comes from the nearest ancestor that specified
For a CoerceValueCallback, the new value will replace an existing
CoerceValueCallbackvalue. If you don't specify a
CoerceValueCallbackin the override metadata, the value comes from the nearest ancestor in the inheritance chain that specified a
FrameworkPropertyMetadatanon-inherited flags, you can override the default
falsevalue with a
truevalue. However, you can only override a
truevalue with a
falsevalue for Inherits, Journal, OverridesInheritanceBehavior, and SubPropertiesDoNotAffectRender.
The default merge logic is implemented by the Merge method. You can specify custom merge logic in a derived class that inherits a dependency property, by overriding
Merge in that class.