Benutzerdefinierte AbhängigkeitseigenschaftenCustom Dependency Properties

Dieses Thema beschreibt die Gründe, warum Anwendungsentwickler und Komponentenautoren in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) benutzerdefinierte Abhängigkeitseigenschaften erstellen möchten, und beschreibt die Implementierungsmaßnahmen und -optionen, die die Leistung, Verwendbarkeit oder Vielseitigkeit der Eigenschaft verbessern können.This topic describes the reasons that Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) application developers and component authors might want to create custom dependency property, and describes the implementation steps as well as some implementation options that can improve performance, usability, or versatility of the property.

VorraussetzungenPrerequisites

In diesem Thema wird vorausgesetzt, dass Sie sich mit Abhängigkeitseigenschaften aus Sicht von vorhandenen Abhängigkeitseigenschaften von Consumern in WPFWPF-Klassen auskennen, und dass Sie das Thema Übersicht über Abhängigkeitseigenschaften gelesen haben.This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on WPFWPF classes, and have read the Dependency Properties Overview topic. Um den Beispielen in diesem Thema zu folgen, sollten Sie zudem mit Extensible Application Markup Language (XAML)Extensible Application Markup Language (XAML) vertraut sein und wissen, wie WPFWPF-Anwendungen geschrieben werden.In order to follow the examples in this topic, you should also understand Extensible Application Markup Language (XAML)Extensible Application Markup Language (XAML) and know how to write WPFWPF applications.

Was ist eine Abhängigkeitseigenschaft?What Is a Dependency Property?

Sie können eine Eigenschaft aktivieren, die normalerweise eine Common Language Runtime (CLR)common language runtime (CLR)-Eigenschaft wäre, um die Verwendung von Stilen, Datenbindung, Vererbung, Animationen und Standardwerten zu unterstützen, indem Sie sie als Abhängigkeitseigenschaft implementieren.You can enable what would otherwise be a Common Language Runtime (CLR)common language runtime (CLR) property to support styling, data binding, inheritance, animations, and default values by implementing it as a dependency property. Abhängigkeitseigenschaften sind Eigenschaften, die bei registriert sind die WPFWPF -Eigenschaftensystem durch Aufruf der Register Methode (oder RegisterReadOnly), und, verfügen über eine DependencyProperty Feld "ID".Dependency properties are properties that are registered with the WPFWPF property system by calling the Register method (or RegisterReadOnly), and that are backed by a DependencyProperty identifier field. Abhängigkeitseigenschaften können nur verwendet werden DependencyObject Typen jedoch DependencyObject ist sehr weit oben in der WPFWPF Klassenhierarchie, damit die Mehrzahl der in verfügbaren Klassen WPFWPF Abhängigkeitseigenschaften unterstützen kann.Dependency properties can be used only by DependencyObject types, but DependencyObject is quite high in the WPFWPF class hierarchy, so the majority of classes available in WPFWPF can support dependency properties. Weitere Informationen zu Abhängigkeitseigenschaften und zur Terminologie und den Konventionen für die Beschreibung in SDKSDK finden Sie unter Übersicht über Abhängigkeitseigenschaften.For more information about dependency properties and some of the terminology and conventions used for describing them in this SDKSDK, see Dependency Properties Overview.

Beispiele für AbhängigkeitseigenschaftenExamples of Dependency Properties

Beispiele für Abhängigkeitseigenschaften, die auf implementiert werden WPFWPF Klassen umfassen die Background -Eigenschaft, die Width -Eigenschaft, und die Text neben vielen anderen-Eigenschaft.Examples of dependency properties that are implemented on WPFWPF classes include the Background property, the Width property, and the Text property, among many others. Jede Abhängigkeitseigenschaft, die von einer Klasse verfügbar gemacht werden, hat ein entsprechendes öffentliche statische Feld vom Typ DependencyProperty für dieselbe Klasse verfügbar gemacht werden.Each dependency property exposed by a class has a corresponding public static field of type DependencyProperty exposed on that same class. Es handelt sich um den Bezeichner für die Abhängigkeitseigenschaft.This is the identifier for the dependency property. Der Name des Bezeichners wird nach einer Konvention gewählt: Der Name der Abhängigkeitseigenschaft mit der angefügten Zeichenfolge Property.The identifier is named using a convention: the name of the dependency property with the string Property appended to it. Z. B. das entsprechende DependencyProperty Bezeichnerfeld für die Background Eigenschaft BackgroundProperty.For example, the corresponding DependencyProperty identifier field for the Background property is BackgroundProperty. Der Bezeichner speichert die Informationen zur Abhängigkeitseigenschaft aus, wie er registriert wurde, und der Bezeichner wird dann später für andere Vorgänge im Zusammenhang mit der Abhängigkeitseigenschaft, wie ein Aufruf verwendet SetValue.The identifier stores the information about the dependency property as it was registered, and the identifier is then used later for other operations involving the dependency property, such as calling SetValue.

Wie in Übersicht über Abhängigkeitseigenschaften erwähnt, sind alle Abhängigkeitseigenschaften in WPFWPF (mit Ausnahme der meisten angefügten Eigenschaften) aufgrund der „Wrapper“-Implementierung auch CLRCLR-Eigenschaften.As mentioned in the Dependency Properties Overview, all dependency properties in WPFWPF (except most attached properties) are also CLRCLR properties because of the "wrapper" implementation. Daher können Sie über Code Abhängigkeitseigenschaften abrufen oder festlegen, indem Sie CLRCLR-Accessoren aufrufen, die die Wrapper in der Art definieren, in der Sie auch andere CLRCLR-Eigenschaften verwenden würden.Therefore, from code, you can get or set dependency properties by calling CLRCLR accessors that define the wrappers in the same manner that you would use other CLRCLR properties. Als Consumer von geltenden Abhängigkeitseigenschaften, Sie in der Regel verwenden Sie nicht die DependencyObject Methoden GetValue und SetValue, die den Verbindungspunkt zum zugrundeliegenden Eigenschaftensystem handelt sind.As a consumer of established dependency properties, you do not typically use the DependencyObject methods GetValue and SetValue, which are the connection point to the underlying property system. Vielmehr die vorhandene Implementierung von der CLRCLR Eigenschaften haben bereits aufgerufen GetValue und SetValue innerhalb der get und set Wrapper-Implementierung der Eigenschaft, verwenden das Bezeichnerfeld entsprechend .Rather, the existing implementation of the CLRCLR properties will have already called GetValue and SetValue within the get and set wrapper implementations of the property, using the identifier field appropriately. Wenn Sie eine benutzerdefinierte Abhängigkeitseigenschaft selbst implementieren, definieren Sie den Wrapper auf ähnliche Weise.If you are implementing a custom dependency property yourself, then you will be defining the wrapper in a similar way.

Wann sollten Sie eine Abhängigkeitseigenschaft implementieren?When Should You Implement a Dependency Property?

Bei der Implementierung einer Eigenschaft für eine Klasse, solange Ihre Klasse abgeleitet DependencyObject, Sie haben die Möglichkeit zum Sichern der Eigenschaft mit einer DependencyProperty Bezeichner und somit zu eine Abhängigkeitseigenschaft zu erleichtern.When you implement a property on a class, so long as your class derives from DependencyObject, you have the option to back your property with a DependencyProperty identifier and thus to make it a dependency property. Es ist nicht immer notwendig oder angemessen, Ihre Eigenschaft in eine Abhängigkeitseigenschaft umzuwandeln. Es hängt von den Anforderungen Ihres Szenarios ab.Having your property be a dependency property is not always necessary or appropriate, and will depend on your scenario needs. Manchmal ist die normale Technik des Sicherns der Eigenschaft mit einem privaten Feld ausreichend.Sometimes, the typical technique of backing your property with a private field is adequate. Sie sollten Ihre Eigenschaft allerdings als Abhängigkeitseigenschaft implementieren, wenn Sie möchten, dass Ihre Eigenschaft eine oder mehrere der folgenden WPFWPF-Funktionen unterstützt:However, you should implement your property as a dependency property whenever you want your property to support one or more of the following WPFWPF capabilities:

  • Sie möchten, dass Ihre Eigenschaft in einem Stil festgelegt werden kann.You want your property to be settable in a style. Weitere Informationen finden Sie unter Erstellen von Formaten und Vorlagen.For more information, see Styling and Templating.

  • Sie möchten, dass die Eigenschaft Datenbindung unterstützt.You want your property to support data binding. Weitere Informationen zur Datenbindung mit Abhängigkeitseigenschaften finden Sie unter Binden der Eigenschaften von zwei Steuerelementen.For more information about data binding dependency properties, see Bind the Properties of Two Controls.

  • Sie möchten, dass die Eigenschaft mit einem dynamischen Ressourcenverweis festgelegt werden kann.You want your property to be settable with a dynamic resource reference. Weitere Informationen finden Sie unter XAML-Ressourcen.For more information, see XAML Resources.

  • Sie möchten einen Eigenschaftswert automatisch von einem übergeordneten Element in der Elementstruktur erben.You want to inherit a property value automatically from a parent element in the element tree. In diesem Fall registrieren mit dem RegisterAttached -Methode, selbst wenn Sie ebenfalls einen Eigenschaftenwrapper für erstellen CLRCLR Zugriff.In this case, register with the RegisterAttached method, even if you also create a property wrapper for CLRCLR access. Weitere Informationen finden Sie unter Vererbung von Eigenschaftswerten.For more information, see Property Value Inheritance.

  • Sie möchten, dass Ihre Eigenschaft animiert werden kann.You want your property to be animatable. Weitere Informationen finden Sie unter Übersicht über Animation.For more information, see Animation Overview.

  • Sie möchten, dass das Eigenschaftensystem berichtet, wenn der vorherige Wert der Eigenschaft durch Aktionen des Eigenschaftensystems, der Umgebung, des Benutzers oder durch Lesen und Verwenden von Stilen geändert wurde.You want the property system to report when the previous value of the property has been changed by actions taken by the property system, the environment, or the user, or by reading and using styles. Mithilfe von Eigenschaftenmetadaten kann Ihre Eigenschaft eine Rückrufmethode angeben, die jedes Mal aufgerufen wird, wenn das Eigenschaftensystem feststellt, dass der Eigenschaftswert eindeutig geändert wurde.By using property metadata, your property can specify a callback method that will be invoked each time the property system determines that your property value was definitively changed. Ein verwandtes Konzept ist die Koersion des Eigenschaftswerts.A related concept is property value coercion. Weitere Informationen finden Sie unter Rückrufe und Validierung von Abhängigkeitseigenschaften.For more information, see Dependency Property Callbacks and Validation.

  • Sie möchten geltende Konventionen für Metadaten verwenden, die auch von WPFWPF-Vorgängen verwendet werden, z.B. der Bericht, ob das Layoutsystem aufgrund eines geänderten Eigenschaftswerts die visuellen Objekte für ein Element neu aufbauen soll.You want to use established metadata conventions that are also used by WPFWPF processes, such as reporting whether changing a property value should require the layout system to recompose the visuals for an element. Oder Sie möchten Überschreibungen von Metadaten verwenden, sodass abgeleitete Klassen auf Metadaten basierende Eigenschaften, z.B. den Standardwert, ändern können.Or you want to be able to use metadata overrides so that derived classes can change metadata-based characteristics such as the default value.

  • Sie möchten die Eigenschaften eines benutzerdefinierten Steuerelements zum Empfangen von WPF-Designer von Visual Studio-support, wie z.B. Eigenschaften Bearbeiten des Fensters.You want properties of a custom control to receive Visual Studio WPF Designer support, such as Properties window editing. Weitere Informationen finden Sie unter Übersicht über das Erstellen von Steuerelementen.For more information, see Control Authoring Overview.

Wenn Sie diese Szenarios untersuchen, sollten Sie auch bedenken, ob Sie Ihr Szenario erreichen können, indem Sie die Metadaten einer vorhandenen Abhängigkeitseigenschaft überschreiben, anstatt eine völlig neue Eigenschaft zu implementieren.When you examine these scenarios, you should also consider whether you can achieve your scenario by overriding the metadata of an existing dependency property, rather than implementing a completely new property. Ob die Überschreibung von Metadaten sinnvoll ist hängt von Ihrem Szenario ab und wie sehr dieses Szenario der Implementierung vorhandener WPFWPF-Abhängigkeitseigenschaften und -Klassen ähnelt.Whether a metadata override is practical depends on your scenario and how closely that scenario resembles the implementation in existing WPFWPF dependency properties and classes. Weitere Informationen zum Überschreiben der Metadaten von vorhandenen Eigenschaften finden Sie unter Metadaten für Abhängigkeitseigenschaften.For more information about overriding metadata on existing properties, see Dependency Property Metadata.

Prüfliste für die Definition einer AbhängigkeitseigenschaftChecklist for Defining a Dependency Property

Das Definieren einer Abhängigkeitseigenschaft besteht aus vier unterschiedlichen Konzepten.Defining a dependency property consists of four distinct concepts. Diese Konzepte sind nicht unbedingt aufeinanderfolgende Schritte, da einige von ihnen am Ende als einzelne Codezeilen in der Implementierung kombiniert werden:These concepts are not necessarily strict procedural steps, because some of these end up being combined as single lines of code in the implementation:

  • (Optional) Erstellen Sie Eigenschaftsmetadaten für die Abhängigkeitseigenschaft.(Optional) Create property metadata for the dependency property.

  • Registrieren Sie den Eigenschaftennamen im Eigenschaftensystem, indem Sie einen Besitzertyp und den Typ des Eigenschaftswerts angeben.Register the property name with the property system, specifying an owner type and the type of the property value. Geben Sie, falls verwendet, auch die Metadaten der Eigenschaft an.Also specify the property metadata, if used.

  • Definieren einer DependencyProperty Bezeichner wie ein public static readonly Feld auf den Besitzertyp.Define a DependencyProperty identifier as a public static readonly field on the owner type.

  • Definieren Sie eine CLRCLR-„Wrapper“-Eigenschaft, deren Name mit dem Namen der Abhängigkeitseigenschaft übereinstimmt.Define a CLRCLR "wrapper" property whose name matches the name of the dependency property. Implementieren Sie die get- und set-Accessoren der CLRCLR-„Wrapper“-Eigenschaft, um eine Verbindung mit der Abhängigkeitseigenschaft herzustellen, die sie sichert.Implement the CLRCLR "wrapper" property's get and set accessors to connect with the dependency property that backs it.

Registrieren der Eigenschaft im EigenschaftensystemRegistering the Property with the Property System

Damit Ihre Eigenschaft zu einer Abhängigkeitseigenschaft wird, müssen Sie diese Eigenschaft in einer Tabelle im Eigenschaftensystem registrieren und einen eindeutigen Bezeichner angeben. Dieser wird als Qualifizierer für spätere Vorgänge im Eigenschaftensystem verwendet.In order for your property to be a dependency property, you must register that property into a table maintained by the property system, and give it a unique identifier that is used as the qualifier for later property system operations. Bei diesen Vorgängen kann es sich um interne Vorgänge oder um Ihr eigenes durch Code aufgerufenes Eigenschaftensystem APIsAPIs handeln.These operations might be internal operations, or your own code calling property system APIsAPIs. Um die Eigenschaft registrieren, rufen Sie die Register Methode innerhalb des Texts der Klasse (innerhalb der Klasse, aber außerhalb von Memberdefinitionen).To register the property, you call the Register method within the body of your class (inside the class, but outside of any member definitions). Das Bezeichnerfeld wird ebenfalls bereitgestellt, durch die Register -Methodenaufruf, als Rückgabewert.The identifier field is also provided by the Register method call, as the return value. Der Grund, die die Register Aufruf erfolgt außerhalb von anderen Definitionen ist, da Sie diesen Rückgabewert verwenden, um zu erstellen und zuzuweisen eine public static readonly -Feld des Typs DependencyProperty als Teil Ihrer Klasse.The reason that the Register call is done outside of other member definitions is because you use this return value to assign and create a public static readonly field of type DependencyProperty as part of your class. Das Feld wird zum Bezeichner für Ihre Abhängigkeitseigenschaft.This field becomes the identifier for your dependency property.

public static readonly DependencyProperty AquariumGraphicProperty = DependencyProperty.Register(
  "AquariumGraphic",
  typeof(Uri),
  typeof(AquariumObject),
  new FrameworkPropertyMetadata(null,
      FrameworkPropertyMetadataOptions.AffectsRender, 
      new PropertyChangedCallback(OnUriChanged)
  )
);
Public Shared ReadOnly AquariumGraphicProperty As DependencyProperty = DependencyProperty.Register("AquariumGraphic", GetType(Uri), GetType(AquariumObject), New FrameworkPropertyMetadata(Nothing, FrameworkPropertyMetadataOptions.AffectsRender, New PropertyChangedCallback(AddressOf OnUriChanged)))

Namenskonventionen für AbhängigkeitseigenschaftenDependency Property Name Conventions

Es gibt Namenskonventionen für Abhängigkeitseigenschaften, die Sie bis auf bestimmte Ausnahmefälle befolgen müssen.There are established naming conventions regarding dependency properties that you must follow in all but exceptional circumstances.

Die Abhängigkeitseigenschaft selbst hat einen einfachen Namen, z.B. "AquariumGraphic" wie in diesem Beispiel, das als der erste Parameter übergeben Register.The dependency property itself will have a basic name, "AquariumGraphic" as in this example, which is given as the first parameter of Register. Dieser Name muss innerhalb jedes Registrierungstyps eindeutig sein.That name must be unique within each registering type. Abhängigkeitseigenschaften, die über Basistypen geerbt werden, gelten bereits als teil des Registrierungstyps. Namen von geerbten Eigenschaften können nicht erneut registriert werden.Dependency properties inherited through base types are considered to be already part of the registering type; names of inherited properties cannot be registered again. Es gibt jedoch ein Verfahren zum Hinzufügen von Klassen als Besitzer einer Abhängigkeitseigenschaft, sogar wenn diese Abhängigkeitseigenschaft nicht geerbt ist. Weitere Informationen hierzu finden Sie unter Metadaten für Abhängigkeitseigenschaften.However, there is a technique for adding a class as owner of a dependency property even when that dependency property is not inherited; for details, see Dependency Property Metadata.

Geben Sie einem Bezeichnerfeld beim Erstellen den Namen der Eigenschaft bei der Registrierung und das Suffix Property.When you create the identifier field, name this field by the name of the property as you registered it, plus the suffix Property. Dieses Feld ist Ihr Bezeichner für die Abhängigkeitseigenschaft, und sie werden später verwendet als Eingabe für die SetValue und GetValue Aufrufe werden in den Wrappern, von allen anderen Codezugriff auf die Eigenschaft über Ihren eigenen Code, indem alle externen Codezugriff, den Sie zulassen , vom Eigenschaftensystem und möglicherweise über XAMLXAML Prozessoren.This field is your identifier for the dependency property, and it will be used later as an input for the SetValue and GetValue calls you will make in the wrappers, by any other code access to the property by your own code, by any external code access you allow, by the property system, and potentially by XAMLXAML processors.

Hinweis

Die übliche Implementierung ist das Definieren der Abhängigkeitseigenschaft im Text einer Klasse. Es ist aber auch möglich, eine Abhängigkeitseigenschaft im statischen Konstruktor der Klasse zu definieren.Defining the dependency property in the class body is the typical implementation, but it is also possible to define a dependency property in the class static constructor. Diese Vorgehensweise kann sinnvoll sein, wenn Sie mehr als eine Codezeile benötigen, um die Abhängigkeitseigenschaft zu initialisieren.This approach might make sense if you need more than one line of code to initialize the dependency property.

Implementieren des „Wrappers“Implementing the "Wrapper"

Sollte Ihre Wrapper-Implementierung aufrufen GetValue in die get -Implementierung und SetValue in die set Implementierung (die ursprüngliche Registrierungs- und sind hier dargestellt zu aus Gründen der Übersichtlichkeit).Your wrapper implementation should call GetValue in the get implementation, and SetValue in the set implementation (the original registration call and field are shown here too for clarity).

In Ausnahmefällen abgesehen sollte Ihre Wrapper-Implementierung nur Ausführen der GetValue und SetValue Aktionen bzw.In all but exceptional circumstances, your wrapper implementations should perform only the GetValue and SetValue actions, respectively. Der Grund hierfür wird im Thema Laden von XAML und Abhängigkeitseigenschaften erläutert.The reason for this is discussed in the topic XAML Loading and Dependency Properties.

Alle vorhandenen öffentlichen Abhängigkeitseigenschaften, die für die WPFWPF-Klassen zur Verfügung stehen, verwenden dieses einfache Modell der Wrapper-Implementierung. Ein Großteil der komplexen Funktionsweise von Abhängigkeitseigenschaften ist entweder ein grundsätzliches Verhalten des Eigenschaftensystems oder wird durch andere Konzepte wie Koersion oder Rückrufe für Eigenschaftenänderungen durch Eigenschaftenmetadaten implementiert.All existing public dependency properties that are provided on the WPFWPF classes use this simple wrapper implementation model; most of the complexity of how dependency properties work is either inherently a behavior of the property system, or is implemented through other concepts such as coercion or property change callbacks through property metadata.


public static readonly DependencyProperty AquariumGraphicProperty = DependencyProperty.Register(
  "AquariumGraphic",
  typeof(Uri),
  typeof(AquariumObject),
  new FrameworkPropertyMetadata(null,
      FrameworkPropertyMetadataOptions.AffectsRender, 
      new PropertyChangedCallback(OnUriChanged)
  )
);
public Uri AquariumGraphic
{
  get { return (Uri)GetValue(AquariumGraphicProperty); }
  set { SetValue(AquariumGraphicProperty, value); }
}

Public Shared ReadOnly AquariumGraphicProperty As DependencyProperty = DependencyProperty.Register("AquariumGraphic", GetType(Uri), GetType(AquariumObject), New FrameworkPropertyMetadata(Nothing, FrameworkPropertyMetadataOptions.AffectsRender, New PropertyChangedCallback(AddressOf OnUriChanged)))
Public Property AquariumGraphic() As Uri
    Get
        Return CType(GetValue(AquariumGraphicProperty), Uri)
    End Get
    Set(ByVal value As Uri)
        SetValue(AquariumGraphicProperty, value)
    End Set
End Property

In diesem Fall gemäß der Konvention der Namen der Wrapper-Eigenschaft muss identisch mit den Namen, ausgewählt und als ersten Parameter die Register Aufruf, der die Eigenschaft registriert.Again, by convention, the name of the wrapper property must be the same as the name chosen and given as first parameter of the Register call that registered the property. Wenn die Eigenschaft den Konventionen nicht folgt, werden dadurch nicht unbedingt alle möglichen Verwendungsarten deaktiviert, aber Sie werden mehrere deutliche Probleme bemerken:If your property does not follow the convention, this does not necessarily disable all possible uses, but you will encounter several notable issues:

  • Bestimmte Aspekte von Stilen und Vorlagen funktionieren nicht.Certain aspects of styles and templates will not work.

  • Die meisten Tools und Designer verlassen sich auf Benennungskonventionen, um XAMLXAML ordnungsgemäß zu serialisieren oder um Unterstützung für eine Entwicklerumgebung auf Ebene einzelner Eigenschaften zu bieten.Most tools and designers must rely on the naming conventions to properly serialize XAMLXAML, or to provide designer environment assistance at a per-property level.

  • Die aktuelle Implementierung des WPFWPF XAMLXAML-Ladeprogramms umgeht die Wrapper komplett und verlässt sich beim Verarbeiten von Attributwerten auf die Benennungskonvention.The current implementation of the WPFWPF XAMLXAML loader bypasses the wrappers entirely, and relies on the naming convention when processing attribute values. Weitere Informationen finden Sie unter Laden von XAML und Abhängigkeitseigenschaften.For more information, see XAML Loading and Dependency Properties.

Eigenschaftsmetadaten für eine neue AbhängigkeitseigenschaftProperty Metadata for a New Dependency Property

Wenn Sie eine Abhängigkeitseigenschaft registrieren, wird bei der Registrierung über das Eigenschaftensystem ein Metadatenobjekt erstellt, das Merkmale der Eigenschaft speichert.When you register a dependency property, the registration through the property system creates a metadata object that stores property characteristics. Viele dieser Merkmale verfügen über Standardwerte, die festgelegt werden, wenn die Eigenschaft, mit einfachen Signaturen von registriert ist Register.Many of these characteristics have defaults that are set if the property is registered with the simple signatures of Register. Andere Signaturen von Register ermöglichen es Ihnen, die Metadaten angeben, wie Sie die Eigenschaft registrieren, werden soll.Other signatures of Register allow you to specify the metadata that you want as you register the property. Die häufigste Art von Metadaten für Abhängigkeitseigenschaften ist ein Standardwert, der für jede neue Instanz angegeben wird, die diese Eigenschaft verwendet.The most common metadata given for dependency properties is to give them a default value that is applied on new instances that use the property.

Bei der Erstellung einer Abhängigkeitseigenschaft, die vorhanden ist auf eine abgeleitete Klasse von FrameworkElement, können Sie die spezialisiertere Metadatenklasse FrameworkPropertyMetadata statt der Base PropertyMetadata Klasse.If you are creating a dependency property that exists on a derived class of FrameworkElement, you can use the more specialized metadata class FrameworkPropertyMetadata rather than the base PropertyMetadata class. Der Konstruktor für die FrameworkPropertyMetadata -Klasse verfügt über mehrere Signaturen, die in dem Sie verschiedene Metadateneigenschaften in Kombination angeben können.The constructor for the FrameworkPropertyMetadata class has several signatures where you can specify various metadata characteristics in combination. Wenn Sie nur den Standardwert angeben möchten, verwenden Sie die Signatur, die einem einzigen vom Typ Parameter Object.If you want to specify the default value only, use the signature that takes a single parameter of type Object. Übergeben Sie diesen Objektparameter als typspezifischen Standardwert für die Eigenschaft (der angegebene Standardwert muss den Typ, die Sie angegeben haben, als die propertyType Parameter in der Register aufrufen).Pass that object parameter as a type-specific default value for your property (the default value provided must be the type you provided as the propertyType parameter in the Register call).

Für FrameworkPropertyMetadata, Sie können auch Optionsflags für Metadaten für die Eigenschaft angeben.For FrameworkPropertyMetadata, you can also specify metadata option flags for your property. Diese Flags werden nach der Registrierung in diskrete Eigenschaften auf den Eigenschaftenmetadaten konvertiert und werden verwendet, um bestimmte Bedingungen an andere Prozesse zu kommunizieren, z.B. an die Layout-Engine.These flags are converted into discrete properties on the property metadata after registration and are used to communicate certain conditionals to other processes such as the layout engine.

Festlegen von Flags für die entsprechenden MetadatenSetting Appropriate Metadata Flags

  • Wenn Ihre Eigenschaft (oder Änderungen an deren Werten) wirkt sich auf die Benutzeroberfläche (User Interface, UI)user interface (UI), und insbesondere wirkt sich auf wie das Layoutsystem oder rendert, sollten Ihr Element auf einer Seite legen Sie eine oder mehrere der folgenden Flags: AffectsMeasure, AffectsArrange, AffectsRender.If your property (or changes in its value) affects the Benutzeroberfläche (User Interface, UI)user interface (UI), and in particular affects how the layout system should size or render your element in a page, set one or more of the following flags: AffectsMeasure, AffectsArrange, AffectsRender.

    • AffectsMeasure Gibt an, dass eine Änderung dieser Eigenschaft eine Änderung an erfordert UIUI rendern, in denen das enthaltende Objekt möglicherweise mehr oder weniger Platz innerhalb des übergeordneten Elements.AffectsMeasure indicates that a change to this property requires a change to UIUI rendering where the containing object might require more or less space within the parent. Für die Eigenschaft „Breite“ sollte beispielsweise dieses Flag festgelegt sein.For example, a "Width" property should have this flag set.

    • AffectsArrange Gibt an, dass eine Änderung dieser Eigenschaft eine Änderung an erfordert UIUI rendern, die in der Regel eine Änderung in den vorgesehenen Platz ist nicht erforderlich, aber gibt an, dass die Positionierung innerhalb des Bereichs geändert wurde.AffectsArrange indicates that a change to this property requires a change to UIUI rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. Für die Eigenschaft „Ausrichtung“ sollte beispielsweise dieses Flag festgelegt sein.For example, an "Alignment" property should have this flag set.

    • AffectsRender Gibt an, dass eine andere Änderung, die aufgetreten ist keine Auswirkung auf Layout und Maße, aber eine andere Rendering erfordert.AffectsRender indicates that some other change has occurred that will not affect layout and measure, but does require another render. Ein Beispiel wäre eine Eigenschaft, die eine Farbe eines vorhandenen Elements ändert, z.B. „Hintergrund“.An example would be a property that changes a color of an existing element, such as "Background".

    • Diese Flags werden in Metadaten häufig als ein Protokoll für Ihre eigenen Überschreibungsimplementierungen von Eigenschaftensystem oder Layoutrückrufen verwendet.These flags are often used as a protocol in metadata for your own override implementations of property system or layout callbacks. Beispielsweise ist es möglich, Sie müssen möglicherweise ein OnPropertyChanged Rückruf, der aufgerufen wird InvalidateArrange Wenn eine Eigenschaft der Instanz Änderung eines Werts berichtet und AffectsArrange als true in seinen Metadaten.For instance, you might have an OnPropertyChanged callback that will call InvalidateArrange if any property of the instance reports a value change and has AffectsArrange as true in its metadata.

  • Manche Eigenschaften können Auswirkungen auf die Merkmale des Renderings des übergeordneten Elements haben, sowohl über und unter den Änderungen der oben genannten benötigten Größe.Some properties may affect the rendering characteristics of the containing parent element, in ways above and beyond the changes in required size mentioned above. Ein Beispiel ist die MinOrphanLines Eigenschaft, die im Flussdokumentmodell, verwendet, in dem Änderungen an dieser Eigenschaft das allgemeine Rendering des Flussdokuments ändern können, das den Absatz enthält.An example is the MinOrphanLines property used in the flow document model, where changes to that property can change the overall rendering of the flow document that contains the paragraph. Verwendung AffectsParentArrange oder AffectsParentMeasure um ähnliche Fälle in Ihren eigenen Eigenschaften zu identifizieren.Use AffectsParentArrange or AffectsParentMeasure to identify similar cases in your own properties.

  • Standardmäßig unterstützen Abhängigkeitseigenschaften die Datenbindung.By default, dependency properties support data binding. Sie können die Datenbindung in Fällen bewusst deaktivieren, in denen kein realistisches Szenario für die Datenbindung besteht, oder in denen die Leistung der Datenbindung für ein großes Objekt als Problem erkannt wird.You can deliberately disable data binding, for cases where there is no realistic scenario for data binding, or where performance in data binding for a large object is recognized as a problem.

  • Standardmäßig wird die Datenbindung Mode Abhängigkeit Eigenschaften standardmäßig auf OneWay.By default, data binding Mode for dependency properties defaults to OneWay. Sie können jederzeit ändern, die Bindung TwoWay pro Bindungsinstanz; ausführliche Informationen finden Sie unter angeben der Bindungsrichtung.You can always change the binding to be TwoWay per binding instance; for details, see Specify the Direction of the Binding. Als Autor der Abhängigkeitseigenschaft, Sie können festlegen, dass die Eigenschaft verwenden, aber TwoWay Bindungsmodus standardmäßig.But as the dependency property author, you can choose to make the property use TwoWay binding mode by default. Ein Beispiel für eine vorhandene Abhängigkeitseigenschaft ist MenuItem.IsSubmenuOpen; das Szenario für diese Eigenschaft ist, die die IsSubmenuOpen Festlegen von Logik und das zusammensetzen von MenuItem mit dem standardmäßigen Designstil interagieren.An example of an existing dependency property is MenuItem.IsSubmenuOpen; the scenario for this property is that the IsSubmenuOpen setting logic and the compositing of MenuItem interact with the default theme style. Die IsSubmenuOpen eigenschaftslogik verwendet die Datenbindung nativ den Status der Eigenschaft in Übereinstimmung mit anderen Zustandseigenschaften und Methodenaufrufen beibehalten.The IsSubmenuOpen property logic uses data binding natively to maintain the state of the property in accordance to other state properties and method calls. Beispiel für eine andere eine Eigenschaft, die gebunden wird TwoWay standardmäßig TextBox.Text.Another example property that binds TwoWay by default is TextBox.Text.

  • Sie können auch die eigenschaftenvererbung in einer benutzerdefinierten Abhängigkeitseigenschaft aktivieren, durch Festlegen der Inherits Flag.You can also enable property inheritance in a custom dependency property by setting the Inherits flag. Eigenschaftenvererbung eignet sich für ein Szenario, in dem übergeordnete und untergeordnete Elemente über eine gemeinsame Eigenschaft verfügen und es sinnvoll ist, dass das untergeordnete Element diesen bestimmten Eigenschaftswert auf den gleichen Wert wie das übergeordnete Element festlegt.Property inheritance is useful for a scenario where parent elements and child elements have a property in common, and it makes sense for the child elements to have that particular property value set to the same value as the parent set it. Eine Beispiel für eine vererbbare Eigenschaft ist DataContext, die für Bindungsvorgänge So aktivieren Sie das wichtige Master / Detail-Szenario für die Darstellung von Daten verwendet wird.An example inheritable property is DataContext, which is used for binding operations to enable the important master-detail scenario for data presentation. Dazu DataContext vererbbar, erben untergeordnete Elemente diesen Datenkontext ebenfalls.By making DataContext inheritable, any child elements inherit that data context also. Aufgrund der Vererbung von Eigenschaftswerten können Sie einen Datenkontext am Seiten- oder Anwendungsstamm angeben, und müssen ihn nicht für Bindungen in allen möglichen untergeordneten Elementen neu angeben.Because of property value inheritance, you can specify a data context at the page or application root, and do not need to respecify it for bindings in all possible child elements. DataContext ist auch ein gutes Beispiel soll verdeutlichen, dass die Vererbung den Standardwert überschreibt, aber es kann immer festgelegt werden lokal auf einem bestimmten untergeordneten Element. Weitere Informationen finden Sie unter verwenden Sie die Master-/ Detailmusters mit hierarchischen Daten.DataContext is also a good example to illustrate that inheritance overrides the default value, but it can always be set locally on any particular child element; for details, see Use the Master-Detail Pattern with Hierarchical Data. Die Vererbung von Eigenschaftswerten kann zu Leistungseinbußen führen und sollte deswegen nur sparsam eingesetzt werden. Weitere Informationen hierzu finden Sie unter Vererbung von Eigenschaftswerten.Property value inheritance does have a possible performance cost, and thus should be used sparingly; for details, see Property Value Inheritance.

  • Legen Sie die Journal Flag, das anzeigt, wenn Ihre Abhängigkeitseigenschaft ermittelt oder von Navigation Journaling-Diensten verwendet werden soll.Set the Journal flag to indicate if your dependency property should be detected or used by navigation journaling services. Ein Beispiel ist die SelectedIndex Eigenschaft; ausgewähltes Element in einer Auswahl Kontrolle beibehalten werden soll, wenn die Journaling-Historie navigiert wird.An example is the SelectedIndex property; any item selected in a selection control should be persisted when the journaling history is navigated.

Schreibgeschützte AbhängigkeitseigenschaftenRead-Only Dependency Properties

Sie können eine Abhängigkeitseigenschaft definieren, die schreibgeschützt ist.You can define a dependency property that is read-only. Allerdings unterscheiden sich die Szenarios, warum Sie eine Eigenschaft als schreibgeschützt definieren sollen. Dies ist auch beim Registrieren mit dem Eigenschaftensystem und Verfügbar machen des Bezeichners der Fall.However, the scenarios for why you might define your property as read-only are somewhat different, as is the procedure for registering them with the property system and exposing the identifier. Weitere Informationen finden Sie unter Schreibgeschützte Abhängigkeitseigenschaften.For more information, see Read-Only Dependency Properties.

Abhängigkeitseigenschaften vom AuflistungstypCollection-Type Dependency Properties

Bei Abhängigkeitseigenschaften vom Auflistungstyp gibt es zusätzliche Implementierungsprobleme, die man berücksichtigen sollte.Collection-type dependency properties have some additional implementation issues to consider. Weitere Informationen finden Sie unter Abhängigkeitseigenschaften vom Auflistungstyp.For details, see Collection-Type Dependency Properties.

Überlegungen zur Sicherheit von AbhängigkeitseigenschaftenDependency Property Security Considerations

Abhängigkeitseigenschaften sollten als öffentliche Eigenschaften deklariert werden.Dependency properties should be declared as public properties. Bezeichnerfelder für Abhängigkeitseigenschaften sollten als öffentliche statische Felder deklariert werden.Dependency property identifier fields should be declared as public static fields. Auch wenn Sie versuchen, andere Zugriffsebenen zu deklarieren (z.B. geschützt), kann auf eine Abhängigkeitseigenschaft über den Bezeichner in Kombination mit dem Eigenschaftensystem APIsAPIs zugegriffen werden.Even if you attempt to declare other access levels (such as protected), a dependency property can always be accessed through the identifier in combination with the property system APIsAPIs. Sogar auf ein geschütztes Bezeichnerfeld kann möglicherweise Metadaten zur berichterstellung oder Wert Bestimmung APIsAPIs werden, die Teil des Eigenschaftensystems, z. B. LocalValueEnumerator.Even a protected identifier field is potentially accessible because of metadata reporting or value determination APIsAPIs that are part of the property system, such as LocalValueEnumerator. Weitere Informationen finden Sie unter Sicherheit von Abhängigkeitseigenschaften.For more information, see Dependency Property Security.

Abhängigkeitseigenschaften und KlassenkonstruktorenDependency Properties and Class Constructors

Es ist ein allgemeines Prinzip für das Programmieren von verwaltetem Code (oft durch Codeanalysetools wie FxCop erzwungen), dass Klassenkonstruktoren keine virtuellen Methoden aufrufen dürfen.There is a general principle in managed code programming (often enforced by code analysis tools such as FxCop) that class constructors should not call virtual methods. Der Grund hierfür ist, dass Konstruktoren als Basisinitialisierung eines abgeleiteten Klassenkonstruktors aufgerufen werden können. Außerdem erfolgt der Eintritt in die virtuelle Methode über den Konstruktor möglicherweise bei einem unvollständigen Initialisierungszustand der erstellten Objektinstanz.This is because constructors can be called as base initialization of a derived class constructor, and entering the virtual method through the constructor might occur at an incomplete initialization state of the object instance being constructed. Beim Ableiten von der Klasse, die bereits von abgeleitet DependencyObject, sollten Sie bedenken, dass das Eigenschaftensystem selbst macht virtuelle Methoden intern aufruft.When you derive from any class that already derives from DependencyObject, you should be aware that the property system itself calls and exposes virtual methods internally. Diese virtuellen Methoden sind Teil der WPFWPF-Dienste für das Eigenschaftensystem.These virtual methods are part of the WPFWPF property system services. Das Überschreiben der Methoden ermöglicht abgeleiteten Klassen,beim Festlegen von Werten teilzunehmen.Overriding the methods enables derived classes to participate in value determination. Sie sollten die Werte der Abhängigkeitseigenschaft innerhalb von Klassenkonstruktoren nicht festlegen, solange Sie keinem sehr spezifischen Konstruktormuster folgen, um potentielle Probleme bei der Initialisierung der Runtime zu vermeiden.To avoid potential issues with runtime initialization, you should not set dependency property values within constructors of classes, unless you follow a very specific constructor pattern. Weitere Informationen finden Sie unter Sichere Konstruktormuster für DependencyObjects.For details, see Safe Constructor Patterns for DependencyObjects.

Siehe auchSee also