依存関係プロパティのメタデータDependency Property Metadata

プロパティWindows Presentation Foundation (WPF)Windows Presentation Foundation (WPF)システムには、リフレクションまたは一般的な共通言語ランタイム (CLR) の特性によってプロパティについて報告できる値を超えるメタデータレポートシステムが含まれています。The Windows Presentation Foundation (WPF)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.

必須コンポーネントPrerequisites

このトピックでは、ユーザーが Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) クラスの既存の依存関係プロパティの使用という観点から依存関係プロパティを理解し、「依存関係プロパティの概要」トピックを通読していることを前提としています。This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) classes, and have read the Dependency Properties Overview. このトピックの例を理解するには、XAMLXAML について理解し、WPFWPF アプリケーションの作成方法に精通している必要があります。In order to follow the examples in this topic, you should also understand XAMLXAML and know how to write WPFWPF 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:

  • 依存関係プロパティの既定値 (ローカル値、スタイル、継承などによってその他の依存関係プロパティ値が指定されない場合)。依存関係プロパティの値を割り当てる際の、既定値と、プロパティ システムで使用される優先順位の関係に関する詳細な説明については、「依存関係プロパティ値の優先順位」を参照してください。Default value for the dependency property, if no other value can be determined for the dependency property by local value, style, inheritance, etc. For a thorough discussion of how default values participate in the precedence used by the property system when assigning values for dependency properties, see Dependency Property Value Precedence.

  • 所有者型に基づく強制型変換または変更通知の動作に影響を与えるコールバック実装への参照。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 Dependency Property Callbacks and Validation.

  • 対象の依存関係プロパティが WPF フレームワーク レベルのプロパティと見なされる場合、WPF フレームワーク レベルの依存関係プロパティ特性がメタデータに含まれる可能性があります。これは、WPF フレームワーク レベルのレイアウト エンジンやプロパティ継承ロジックなどのサービスの情報および状態を報告します。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 Framework Property Metadata.

メタデータ APIMetadata APIs

プロパティシステムによって使用されるほとんどのメタデータ情報を報告するPropertyMetadata型は、クラスです。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. (プロパティの登録でメタデータが指定されていないPropertyMetadata場合は、そのクラスの既定値を使用して既定値が作成されます)。登録されたメタデータPropertyMetadataは、 DependencyObjectインスタンスの依存GetMetadata関係プロパティからメタデータを取得するさまざまなオーバーロードを呼び出すと、として返されます。(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.

PropertyMetadataに、クラスをから派生させることにより、WPF フレームワークレベルのクラスなどのアーキテクチャの区分に対して、より具体的なメタデータを提供します。The PropertyMetadata class is then derived from to provide more specific metadata for architectural divisions such as the WPF framework-level classes. UIPropertyMetadataアニメーションレポートを追加しFrameworkPropertyMetadata 、前のセクションで説明した WPF フレームワークレベルのプロパティを提供します。UIPropertyMetadata adds animation reporting, and FrameworkPropertyMetadata provides the WPF framework-level properties mentioned in the previous section. 依存関係プロパティが登録されると、これらPropertyMetadataの派生クラスに登録できます。When dependency properties are registered, they can be registered with these PropertyMetadata derived classes. メタデータが検査されると、 PropertyMetadata基本型を派生クラスにキャストして、より具体的なプロパティを調べることができる可能性があります。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.

注意

FrameworkPropertyMetadata指定できるプロパティ特性は、このドキュメントでは "flags" と呼ばれることもあります。The property characteristics that can be specified in FrameworkPropertyMetadata are sometimes referred to in this documentation as "flags". 依存関係プロパティの登録またはメタデータのオーバーライドで使用する新しいメタデータインスタンスを作成する場合は、 FrameworkPropertyMetadataOptionsフラグ列挙体を使用してこれらの値を指定します。その後、列挙体の値を連結します。FrameworkPropertyMetadataコンストラクター。When you create new metadata instances for use in dependency property registrations or metadata overrides, you specify these values using the flagwise enumeration FrameworkPropertyMetadataOptions and then you supply possibly concatenated values of the enumeration to the FrameworkPropertyMetadata constructor. ただし、構築されると、これらのオプション特性はFrameworkPropertyMetadata 、の構築列挙値ではなく一連のブール型プロパティとして内に公開されます。However, once constructed, these option characteristics are exposed within a FrameworkPropertyMetadata as a series of Boolean properties rather than the constructing enumeration value. これらのブール型プロパティを使用すると、目的の情報を取得するためにフラグ列挙値に対してマスクを適用することなく、各条件をチェックすることができます。The Boolean properties enable you to check each conditional, rather than requiring you to apply a mask to a flagwise enumeration value to get the information you are interested in. コンストラクターは、コンストラクターシグネチャFrameworkPropertyMetadataOptionsの長さを適切に保つために、連結されたを使用します。一方、実際に構築されたメタデータは、メタデータのクエリをより直観的に行うために個別のプロパティを公開します。The constructor uses the concatenated FrameworkPropertyMetadataOptions in order to keep the length of the constructor signature reasonable, whereas the actual constructed metadata exposes the discrete properties to make querying the metadata more intuitive.

メタデータをオーバーライドする場合、クラスを派生する場合When to Override Metadata, When to Derive a Class

WPFWPF プロパティ システムには、依存関係プロパティを完全に再実装することなく、依存関係プロパティの一部の特性を変更するための機能が用意されています。The WPFWPF 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. 既存の依存関係プロパティの大部分は仮想プロパティではありません。したがって、厳密には、継承クラスでの依存関係プロパティの "再実装" は、既存のメンバーをシャドウすることによってのみ実現されます。Note that most existing dependency properties are not virtual properties, so strictly speaking "re-implementing" them on inherited classes could only be accomplished by shadowing the existing member.

型の依存関係プロパティに対して有効にしようとしているシナリオが、既存の依存関係プロパティの特性の変更では実現できない場合、派生クラスを作成し、その派生クラスでカスタム依存関係プロパティを宣言することが必要になる場合があります。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. カスタム依存関係プロパティは、 WPFWPF api によって定義された依存関係プロパティと同じように動作します。A custom dependency property behaves identically to dependency properties defined by the WPFWPF APIs. カスタム依存関係プロパティの詳細については、「カスタム依存関係プロパティ」を参照してください。For more details about custom dependency properties, see Custom Dependency Properties.

オーバーライドすることができない依存関係プロパティの代表的な特性の 1 つは、依存関係プロパティの値型です。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. また、このコールバックは、 ValidateValueCallbackメタデータ内ではなく登録フィールド自体に存在するため、既存のを置き換えることはできません。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

既存の依存関係プロパティのメタデータを使用している場合、依存関係プロパティのメタデータを変更する一般的なシナリオの 1 つは、既定値を変更することです。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. コードと宣言的な使用方法の両方をサポートするプログラミング モデルを使用する条件の 1 つとして、プロパティを任意の順序で設定できる必要があります。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. したがって、依存関係プロパティはすべて、コンテキストを使用せずに Just-In-Time で設定する必要があります。また、設定順序 (コンストラクター内の順序など) に依存することもできません。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 Dependency Property Callbacks and Validation. 検証コールバックは、メタデータの一部ではなく、依存関係プロパティ識別子の一部であることに注意してください。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.

既存の依存関係プロパティに対して、WPF フレームワーク レベルのプロパティのメタデータ オプションの変更が必要になる場合があります。In some cases you might also want to alter the WPF framework-level property metadata options on existing dependency properties. これらのオプションは、WPF フレームワーク レベルのプロパティに関する特定の既知の条件を、レイアウト システムなどの他の WPF フレームワーク レベルのプロセスに伝達します。These options communicate certain known conditionals about WPF framework-level properties to other WPF framework-level processes such as the layout system. オプションの設定は、通常、新しい依存関係プロパティを登録するときにのみ実行されますが、 OverrideMetadataまたはAddOwnerの呼び出しの一部として、WPF フレームワークレベルのプロパティのメタデータを変更することもできます。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 Framework Property Metadata. 新しく登録した依存関係プロパティに対してこれらのオプションを設定する方法の詳細については、「カスタム依存関係プロパティ」を参照してください。For more information that is pertinent to how these options should be set for a newly registered dependency property, see Custom Dependency Properties.

メタデータのオーバーライド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 Override Metadata for a Dependency Property.

登録呼び出し中に依存関係プロパティのプロパティメタデータを指定できRegisterます ()。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. これは、 OverrideMetadataメソッドを呼び出すことによって行うことができます。You can do this by calling the OverrideMetadata method. Api WPFWPF の例Focusableとして、クラスは、最初に依存関係プロパティを登録する型です。FrameworkElementFor an example from the WPFWPF APIs, the FrameworkElement class is the type that first registers the Focusable dependency property. ただし、 Controlクラスは、依存関係プロパティのメタデータをオーバーライドして、独自の初期既定false値を提供し、それをからにFocusable true変更します。それ以外の場合は、元の実装を再利用します。But the Control class overrides metadata for the dependency property to provide its own initial default value, changing it from false to true, and otherwise re-uses the original Focusable implementation.

メタデータをオーバーライドすると、さまざまなメタデータ特性がマージされるか置き換えられます。When you override metadata, the different metadata characteristics are either merged or replaced.

  • PropertyChangedCallbackマージされます。PropertyChangedCallback is merged. 新しいPropertyChangedCallbackを追加すると、そのコールバックがメタデータに格納されます。If you add a new PropertyChangedCallback, that callback is stored in the metadata. オーバーライドでをPropertyChangedCallback指定しない場合、のPropertyChangedCallback値はメタデータで指定された最も近い先祖から参照として昇格されます。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.

  • PropertyChangedCallback実際のプロパティシステムの動作では、階層内のすべてのメタデータ所有者の実装が保持され、テーブルに追加されます。プロパティシステムによって実行される順序により、最も多くの派生クラスのコールバックが最初に呼び出されることになります。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が置き換えられます。DefaultValue is replaced. オーバーライドでをDefaultValue指定しない場合、のDefaultValue値は、メタデータで指定された最も近い先祖から取得されます。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実装は置き換えられます。CoerceValueCallback implementations are replaced. 新しいCoerceValueCallbackを追加すると、そのコールバックがメタデータに格納されます。If you add a new CoerceValueCallback, that callback is stored in the metadata. オーバーライドでをCoerceValueCallback指定しない場合、のCoerceValueCallback値はメタデータで指定された最も近い先祖から参照として昇格されます。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.

  • プロパティシステムの動作は、直接のCoerceValueCallbackメタデータ内ののみが呼び出されることを示します。The property system behavior is that only the CoerceValueCallback in the immediate metadata is invoked. 階層内の他CoerceValueCallbackの実装への参照は保持されません。No references to other CoerceValueCallback implementations in the hierarchy are retained.

この動作はによっMergeて実装され、派生メタデータクラスでオーバーライドできます。This behavior is implemented by Merge, and can be overridden on derived metadata classes.

添付プロパティのメタデータのオーバーライドOverriding Attached Property Metadata

WPFWPF では、添付プロパティは依存関係プロパティとして実装されます。In WPFWPF, attached properties are implemented as dependency properties. このことは、添付プロパティもプロパティ メタデータを持ち、これを個々のクラスでオーバーライドできることを意味します。This means that they also have property metadata, which individual classes can override. WPFWPF添付プロパティのスコープに関する考慮事項は、通常DependencyObject 、添付プロパティが設定されている場合があります。The scoping considerations for an attached property in WPFWPF are generally that any DependencyObject can have an attached property set on them. したがって、 DependencyObjectクラスのインスタンスに設定されている可能性があるため、任意の派生クラスで、添付プロパティのメタデータをオーバーライドできます。Therefore, any DependencyObject derived class can override the metadata for any attached property, as it might be set on an instance of the class. オーバーライドできるのは、既定値、コールバック、または WPF フレームワーク レベルの特性報告プロパティです。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.

注意

プロパティInheritsは、添付プロパティには関係ありません。The Inherits property is not relevant for attached properties.

既存の依存関係プロパティの所有者としてのクラスの追加Adding a Class as an Owner of an Existing Dependency Property

クラスは、 AddOwnerメソッドを使用して、既に登録されている依存関係プロパティの所有者として自身を追加できます。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. このフィールドは、 public static readonly AddOwner呼び出しの戻り値DependencyPropertyに割り当てられる型のフィールドである必要があります。This field should be a public static readonly field of type DependencyProperty, which is assigned to the return value of the AddOwner call. 定義する2番目のメンバーは、共通言語ランタイム (CLR) "ラッパー" プロパティです。The second member to define is the common language runtime (CLR) "wrapper" property. ラッパーを使用すると、コードで依存関係プロパティを操作することがはるかに簡単SetValueになります (毎回の呼び出しを回避し、ラッパー自体で1回だけ呼び出しを行うことができます)。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). このラッパーの実装方法は、カスタム依存関係プロパティを登録する場合の実装方法とまったく同じです。The wrapper is implemented identically to how it would be implemented if you were registering a custom dependency property. 依存関係プロパティの実装の詳細については、「カスタム依存関係プロパティ」および「依存関係プロパティの所有者の種類を追加する」を参照してください。For more information about implementing a dependency property, see Custom Dependency Properties and Add an Owner Type for a Dependency Property.

AddOwner および添付プロパティAddOwner and Attached Properties

Owner クラスにAddOwnerよって添付プロパティとして定義されている依存関係プロパティに対してを呼び出すことができます。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. 次に、依存関係AddOwnerプロパティの識別子とpublic static readonlyして使用するフィールドとして戻り値を公開し、適切な "ラッパー" プロパティを定義します。これにより、プロパティが members テーブルに表示され、添付されていないプロパティがサポートされるようになります。クラスの使用方法。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.

関連項目See also