Metadados de Propriedade de Dependência

The Windows Presentation Foundation (WPF) property system includes a metadata reporting system that goes beyond what can be reported about a property through reflection or general common language runtime (CLR) characteristics. Metadata for a dependency property can also be assigned uniquely by the class that defines a dependency property, can be changed when the dependency property is added to a different class, and can be specifically overridden by all derived classes that inherit the dependency property from the defining base class.

Este tópico contém as seguintes seções.

• Prerequisites
• How Dependency Property Metadata is Used
• Metadata APIs
• When to Override Metadata, When to Derive a Class
• Scenarios for Changing Existing Metadata
• Tópicos relacionados

Prerequisites

This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Windows Presentation Foundation (WPF) classes, and have read the Visão geral sobre propriedades de dependência. In order to follow the examples in this topic, you should also understand XAML and know how to write WPF applications.

How Dependency Property Metadata is Used

Dependency property metadata exists as an object that can be queried to examine the characteristics of a dependency property. This metadata is also accessed frequently by the property system as it processes any given dependency property. The metadata object for a dependency property can contain the following types of information:

• Valor padrão para a propriedade de dependência, se nenhum outro valor pode ser determinado para a propriedade de dependência valor local, estilo, herança, etc. Para obter uma discussão detalhada de como os valores padrão participarem a precedência usada pelo sistema de propriedade ao atribuir valores para propriedades de dependência, consulte Precedência de valores de propriedade de dependência.

• References to callback implementations that affect coercion or change-notification behaviors on a per-owner-type basis. Note that these callbacks are often defined with a nonpublic access level, so obtaining the actual references from metadata is generally not possible unless the references are within your permitted access scope. For more information on dependency property callbacks, see Validação e Callbacks de Propriedade de Dependência.

• If the dependency property in question is considered to be a WPF framework-level property, the metadata might contain WPF framework-level dependency property characteristics, which report information and state for services such as the WPF framework-level layout engine and property inheritance logic. For more information on this aspect of dependency property metadata, see Metadados de Propriedades de Framework.

Metadata APIs

The type that reports most of the metadata information used by the property system is the PropertyMetadata class. Metadata instances are optionally specified when dependency properties are registered with the property system, and can be specified again for additional types that either add themselves as owners or override metadata they inherit from the base class dependency property definition. (For cases where a property registration does not specify metadata, a default PropertyMetadata is created with default values for that class.)The registered metadata is returned as PropertyMetadata when you call the various GetMetadata overloads that get metadata from a dependency property on a DependencyObject instance.

O PropertyMetadata classe é derivada para fornecer metadados mais específicos para as divisões de arquiteturais, como o WPF framework-nível classes. UIPropertyMetadataAdiciona os relatórios de animação, e FrameworkPropertyMetadata fornece a WPF framework-nível propriedades mencionadas na seção anterior. When dependency properties are registered, they can be registered with these PropertyMetadata derived classes. When the metadata is examined, the base PropertyMetadata type can potentially be cast to the derived classes so that you can examine the more specific properties.

When to Override Metadata, When to Derive a Class

The WPF property system has established capabilities for changing some characteristics of dependency properties without requiring them to be entirely re-implemented. This is accomplished by constructing a different instance of property metadata for the dependency property as it exists on a particular type. Observe que as propriedades de dependência mais existentes não são propriedades virtual, então estritamente falando "Reimplementando" -los em classes herdadas poderiam ser realizadas somente por sombreamento o membro existente.

If the scenario you are trying to enable for a dependency property on a type cannot be accomplished by modifying characteristics of existing dependency properties, it might then be necessary to create a derived class, and then to declare a custom dependency property on your derived class. A custom dependency property behaves identically to dependency properties defined by the WPF APIs. For more details about custom dependency properties, see Propriedades de Dependência Personalizada.

One notable characteristic of a dependency property that you cannot override is its value type. If you are inheriting a dependency property that has the approximate behavior you require, but you require a different type for it, you will have to implement a custom dependency property and perhaps link the properties through type conversion or other implementation on your custom class. Also, you cannot replace an existing ValidateValueCallback, because this callback exists in the registration field itself and not within its metadata.

Scenarios for Changing Existing Metadata

If you are working with metadata of an existing dependency property, one common scenario for changing dependency property metadata is to change the default value. Changing or adding property system callbacks is a more advanced scenario. You might want to do this if your implementation of a derived class has different interrelationships between dependency properties. One of the conditionals of having a programming model that supports both code and declarative usage is that properties must enable being set in any order. Thus any dependent properties need to be set just-in-time without context and cannot rely on knowing a setting order such as might be found in a constructor. For more information on this aspect of the property system, see Validação e Callbacks de Propriedade de Dependência. Note that validation callbacks are not part of the metadata; they are part of the dependency property identifier. Therefore, validation callbacks cannot be changed by overriding the metadata.

In some cases you might also want to alter the WPF framework-level property metadata options on existing dependency properties. These options communicate certain known conditionals about WPF framework-level properties to other WPF framework-level processes such as the layout system. Setting the options is generally done only when registering a new dependency property, but it is also possible to change the WPF framework-level property metadata as part of a OverrideMetadata or AddOwner call. For the specific values to use and more information, see Metadados de Propriedades de Framework. For more information that is pertinent to how these options should be set for a newly registered dependency property, see Propriedades de Dependência Personalizada.

Overriding Metadata

The purpose of overriding metadata is primarily so that you have the opportunity to change the various metadata-derived behaviors that are applied to the dependency property as it exists on your type. The reasons for this are explained in more detail in the Metadata section. For more information including some code examples, see Como: Override Metadata for a Dependency Property.

Property metadata can be supplied for a dependency property during the registration call (Register). However, in many cases, you might want to provide type-specific metadata for your class when it inherits that dependency property. You can do this by calling the OverrideMetadata method. Para obter um exemplo da WPF APIs, o FrameworkElement classe é o tipo que registra pela primeira vez o Focusable propriedade de dependência. Mas o Control classe substitui os metadados da propriedade de dependência fornecer seu próprio valor inicial padrão, a alteração de false para truee caso contrário reutiliza o original Focusable de implementação.

When you override metadata, the different metadata characteristics are either merged or replaced.

• PropertyChangedCallback is merged. If you add a new PropertyChangedCallback, that callback is stored in the metadata. If you do not specify a PropertyChangedCallback in the override, the value of PropertyChangedCallback is promoted as a reference from the nearest ancestor that specified it in metadata.

• The actual property system behavior for PropertyChangedCallback is that implementations for all metadata owners in the hierarchy are retained and added to a table, with order of execution by the property system being that the most derived class's callbacks are invoked first.

• DefaultValue is replaced. If you do not specify a DefaultValue in the override, the value of DefaultValue comes from the nearest ancestor that specified it in metadata.

• CoerceValueCallback implementations are replaced. If you add a new CoerceValueCallback, that callback is stored in the metadata. If you do not specify a CoerceValueCallback in the override, the value of CoerceValueCallback is promoted as a reference from the nearest ancestor that specified it in metadata.

• The property system behavior is that only the CoerceValueCallback in the immediate metadata is invoked. No references to other CoerceValueCallback implementations in the hierarchy are retained.

This behavior is implemented by Merge, and can be overridden on derived metadata classes.

Overriding Attached Property Metadata

In WPF, attached properties are implemented as dependency properties. This means that they also have property metadata, which individual classes can override. The scoping considerations for an attached property in WPF are generally that any DependencyObject can have an attached property set on them. Therefore, any DependencyObject derived class can override the metadata for any attached property, as it might be set on an instance of the class. You can override default values, callbacks, or WPF framework-level characteristic-reporting properties. If the attached property is set on an instance of your class, those override property metadata characteristics apply. For instance, you can override the default value, such that your override value is reported as the value of the attached property on instances of your class, whenever the property is not otherwise set.

Adding a Class as an Owner of an Existing Dependency Property

A class can add itself as an owner of a dependency property that has already been registered, by using the AddOwner method. This enables the class to use a dependency property that was originally registered for a different type. The adding class is typically not a derived class of the type that first registered that dependency property as owner. Effectively, this allows your class and its derived classes to "inherit" a dependency property implementation without the original owner class and the adding class being in the same true class hierarchy. In addition, the adding class (and all derived classes as well) can then provide type-specific metadata for the original dependency property.

As well as adding itself as owner through the property system utility methods, the adding class should declare additional public members on itself in order to make the dependency property a full participant in the property system with exposure to both code and markup. A class that adds an existing dependency property has the same responsibilities as far as exposing the object model for that dependency property as does a class that defines a new custom dependency property. The first such member to expose is a dependency property identifier field. This field should be a public static readonly field of type DependencyProperty, which is assigned to the return value of the AddOwner call. The second member to define is the common language runtime (CLR) "wrapper" property. The wrapper makes it much more convenient to manipulate your dependency property in code (you avoid calls to SetValue each time, and can make that call only once in the wrapper itself). O invólucro é implementado de forma idêntica para como ele poderia ser implementado se foram Registrando um personalizado propriedade de dependência. Para obter mais informações sobre como implementar um propriedade de dependência, consulte Propriedades de Dependência Personalizada e Como: Add an Owner Type for a Dependency Property.

AddOwner and Attached Properties

You can call AddOwner for a dependency property that is defined as an attached property by the owner class. Generally the reason for doing this is to expose the previously attached property as a non-attached dependency property. You then will expose the AddOwner return value as a public static readonly field for use as the dependency property identifier, and will define appropriate "wrapper" properties so that the property appears in the members table and supports a non-attached property usage in your class.

Consulte também

Referência

PropertyMetadata

DependencyObject

DependencyProperty

GetMetadata

Conceitos

Visão geral sobre propriedades de dependência

Metadados de Propriedades de Framework