DependencyProperty.OverrideMetadata Method (Type, PropertyMetadata)

Specifies alternate metadata for this dependency property when it is present on instances of a specified type, overriding the metadata that existed for the dependency property as it was inherited from base types.

Namespace:  System.Windows
Assembly:  WindowsBase (in WindowsBase.dll)

public void OverrideMetadata(
	Type forType,
	PropertyMetadata typeMetadata
)

Parameters

forType
Type: System.Type
The type where this dependency property is inherited and where the provided alternate metadata will be applied.
typeMetadata
Type: System.Windows.PropertyMetadata
The metadata to apply to the dependency property on the overriding type.

ExceptionCondition
InvalidOperationException

An attempt was made to override metadata on a read-only dependency property (that operation cannot be done using this signature).

ArgumentException

Metadata was already established for the dependency property as it exists on the provided type.

Dependency property metadata should be overridden before the property system uses the dependency property. This equates to the time that specific instances are created using the class that registers the dependency property. Calls to OverrideMetadata should only be performed within the static constructors of the type that provides itself as the forType parameter of this method, or through similar instantiation. Attempting to change metadata after instances of the owner type exist will not raise exceptions, but will result in inconsistent behaviors in the property system.

After metadata for a particular derived class override is established with this method, subsequent attempts to override metadata on this same derived class will raise an exception.

The supplied metadata is merged with the property metadata for the dependency property as it exists on the base owner. Any characteristics that were specified in the original base metadata will persist; only those characteristics that were specifically changed in the new metadata will override the characteristics of the base metadata. Some characteristics such as DefaultValue are replaced if specified in the new metadata. Others, such as PropertyChangedCallback, are combined. Ultimately, the merge behavior depends on the property metadata type being used for the override, so the behavior described here is for the existing property metadata classes used by WPF dependency properties. For details, see Dependency Property Metadata and Framework Property Metadata.

This example shows how to override default dependency property metadata that comes from an inherited class, by calling the OverrideMetadata method and providing type-specific metadata.

By defining its PropertyMetadata, a class can define the dependency property's behaviors, such as its default value and property system callbacks. Many dependency property classes already have default metadata established as part of their registration process. This includes the dependency properties that are part of the WPF API. A class that inherits the dependency property through its class inheritance can override the original metadata so that the characteristics of the property that can be altered through metadata will match any subclass-specific requirements.

Overriding metadata on a dependency property must be done prior to that property being placed in use by the property system (this equates to the time that specific instances of objects that register the property are instantiated). Calls to OverrideMetadata must be performed within the static constructors of the type that provides itself as the forType parameter of OverrideMetadata. If you attempt to change metadata once instances of the owner type exist, this will not raise exceptions, but will result in inconsistent behaviors in the property system. Also, metadata can only be overridden once per type. Subsequent attempts to override metadata on the same type will raise an exception.

In the following example, the custom class MyAdvancedStateControl overrides the metadata provided for StateProperty by MyAdvancedStateControl with new property metadata. For instance, the default value of the StateProperty is now true when the property is queried on a newly constructed MyAdvancedStateControl instance.


public class MyStateControl : ButtonBase
{
  public MyStateControl() : base() { }
  public Boolean State
  {
    get { return (Boolean)this.GetValue(StateProperty); }
    set { this.SetValue(StateProperty, value); } 
  }
  public static readonly DependencyProperty StateProperty = DependencyProperty.Register(
    "State", typeof(Boolean), typeof(MyStateControl),new PropertyMetadata(false));
}


...


public class MyAdvancedStateControl : MyStateControl
{
  public MyAdvancedStateControl() : base() { }
  static MyAdvancedStateControl()
  {
    MyStateControl.StateProperty.OverrideMetadata(typeof(MyAdvancedStateControl), new PropertyMetadata(true));
  }
}


.NET Framework

Supported in: 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft