Propriétés de dépendance en lecture seuleRead-Only Dependency Properties

Cette rubrique décrit les propriétés de dépendance en lecture seule, y compris les propriétés de dépendance en lecture seule existantes, et les scénarios et techniques de création d’une propriété de dépendance en lecture seule personnalisée.This topic describes read-only dependency properties, including existing read-only dependency properties and the scenarios and techniques for creating a custom read-only dependency property.

Configuration requisePrerequisites

Cette rubrique part du principe que vous comprenez les scénarios de base de l’implémentation d’une propriété de dépendance et que vous savez comment les métadonnées sont appliquées à une propriété de dépendance personnalisée.This topic assumes that you understand the basic scenarios of implementing a dependency property, and how metadata is applied to a custom dependency property. Pour plus d’informations sur le contexte, consultez Propriétés de dépendance personnalisées et Métadonnées de propriété de dépendance.See Custom Dependency Properties and Dependency Property Metadata for context.

Propriétés de dépendance en lecture seule existantesExisting Read-Only Dependency Properties

Certaines des propriétés de dépendance définies dans le framework Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) sont en lecture seule.Some of the dependency properties defined in the Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) framework are read-only. En règle générale, vous définissez des propriétés de dépendance en lecture seule parce qu’elles doivent être utilisées pour déterminer des états. Toutefois, quand l’état est influencé par plusieurs facteurs, le simple fait de définir la propriété sur cet état n’est pas souhaitable du point de vue de la conception de l’interface utilisateur.The typical reason for specifying a read-only dependency property is that these are properties that should be used for state determination, but where that state is influenced by a multitude of factors, but just setting the property to that state isn't desirable from a user interface design perspective. Par exemple, la propriété IsMouseOver est en fait simplement un état de surface déterminé à partir de l’entrée de la souris.For example, the property IsMouseOver is really just surfacing state as determined from the mouse input. Si vous tentez de définir cette valeur par programmation en contournant la vraie entrée de souris, vous obtenez un comportement imprévisible qui entraîne une incohérence.Any attempt to set this value programmatically by circumventing the true mouse input would be unpredictable and would cause inconsistency.

Parce qu’elles ne sont pas définissables, les propriétés de dépendance en lecture seule ne sont pas appropriées dans de nombreux scénarios pour lesquels les propriétés de dépendance offrent normalement une solution (à savoir : liaison de données, style applicable directement à une valeur, validation, animation, héritage).By virtue of not being settable, read-only dependency properties aren't appropriate for many of the scenarios for which dependency properties normally offer a solution (namely: data binding, directly stylable to a value, validation, animation, inheritance). Bien qu’elles ne soient pas définissables, les propriétés de dépendance en lecture seule offrent néanmoins des fonctionnalités supplémentaires prises en charge par les propriétés de dépendance dans le système de propriétés.Despite not being settable, read-only dependency properties still have some of the additional capabilities supported by dependency properties in the property system. La fonctionnalité restante la plus importante est que la propriété de dépendance en lecture seule peut toujours être utilisée comme déclencheur de propriété dans un style.The most important remaining capability is that the read-only dependency property can still be used as a property trigger in a style. Vous ne pouvez pas activer les déclencheurs avec une propriété de common language runtime normale (CLR). il doit s’agir d’une propriété de dépendance.You can't enable triggers with a normal common language runtime (CLR) property; it needs to be a dependency property. La propriété IsMouseOver ci-dessus est un exemple parfait d’un scénario dans lequel il peut être très utile de définir un style pour un contrôle, où une propriété visible telle qu’un arrière-plan, un premier plan ou des propriétés similaires d’éléments composites dans le contrôle changer quand l’utilisateur place une souris sur une zone définie de votre contrôle.The aforementioned IsMouseOver property is a perfect example of a scenario where it might be quite useful to define a style for a control, where some visible property such as a background, foreground, or similar properties of composited elements within the control will change when the user places a mouse over some defined region of your control. Les changements d’une propriété de dépendance en lecture seule peuvent aussi être détectés et signalés par les processus d’invalidation inhérents au système de propriétés, la fonctionnalité de déclencheur de propriété étant prise en charge en interne.Changes in a read-only dependency property can also be detected and reported by the property system's inherent invalidation processes, and this in fact supports the property trigger functionality internally.

Création de propriétés de dépendance en lecture seule personnaliséesCreating Custom Read-Only Dependency Properties

Lisez attentivement la section ci-dessus qui explique pourquoi les propriétés de dépendance en lecture seule ne fonctionnent pas dans de nombreux scénarios de propriété de dépendance classiques.Make sure to read the section above regarding why read-only dependency properties won't work for many typical dependency-property scenarios. Toutefois, si vous avez un scénario approprié, vous pouvez créer votre propre propriété de dépendance en lecture seule.But if you have an appropriate scenario, you may wish to create your own read-only dependency property.

Une grande partie du processus de création d’une propriété de dépendance en lecture seule est identique à celui décrit dans les rubriques Propriétés de dépendance personnalisées et Implémenter une propriété de dépendance.Much of the process of creating a read-only dependency property is the same as is described in the Custom Dependency Properties and Implement a Dependency Property topics. Il existe trois différences majeures :There are three important differences:

  • Lors de l’inscription de votre propriété, appelez la méthode RegisterReadOnly à la place de la méthode Register normale pour l’inscription des propriétés.When registering your property, call the RegisterReadOnly method instead of the normal Register method for property registration.

  • Lors de l’implémentation de la propriété « wrapper » du CLR, assurez-vous que le wrapper n’a pas non plus d’implémentation définie, afin qu’il n’y ait pas d’incohérence dans l’État en lecture seule pour le wrapper public que vous exposez.When implementing the CLR "wrapper" property, make sure that the wrapper too doesn't have a set implementation, so that there is no inconsistency in read-only state for the public wrapper you expose.

  • L’objet retourné par l’inscription en lecture seule est DependencyPropertyKey plutôt que DependencyProperty.The object returned by the read-only registration is DependencyPropertyKey rather than DependencyProperty. Vous devez toujours stocker ce champ sous forme de membre, mais, en général, vous ne le convertissez pas en membre public du type.You should still store this field as a member but typically you would not make it a public member of the type.

Indépendamment de la valeur ou champ privé que vous utilisez, le stockage de votre propriété de dépendance en lecture seule peut être entièrement inscriptible en utilisant la logique de votre choix.Whatever private field or value you have backing your read-only dependency property can of course be fully writable using whatever logic you decide. Toutefois, la méthode la plus simple pour définir la propriété initialement ou dans le cadre de la logique du runtime consiste à utiliser les API du système de propriétés, plutôt que de contourner le système de propriétés et de définir le champ de stockage privé directement.However, the most straightforward way to set the property either initially or as part of runtime logic is to use the property system's APIs, rather than circumventing the property system and setting the private backing field directly. En particulier, il existe une signature de SetValue qui accepte un paramètre de type DependencyPropertyKey.In particular, there is a signature of SetValue that accepts a parameter of type DependencyPropertyKey. Le mode et l’emplacement de définition de cette valeur par programmation dans votre logique d’application affectent la manière dont vous pouvez définir l’accès sur le DependencyPropertyKey créé lorsque vous avez inscrit la propriété de dépendance pour la première fois.How and where you set this value programmatically within your application logic will affect how you may wish to set access on the DependencyPropertyKey created when you first registered the dependency property. Si vous gérez cette logique entièrement dans la classe, vous pouvez indiquer qu’elle est privée ou, si vous voulez qu’elle soit définie à partir d’autres parties de l’assembly, vous pouvez la définir en interne.If you handle this logic all within the class you could make it private, or if you require it to be set from other portions of the assembly you might set it internal. Une approche consiste à appeler SetValue dans un gestionnaire d’événements de classe d’un événement pertinent qui informe une instance de classe que la valeur de propriété stockée doit être modifiée.One approach is to call SetValue within a class event handler of a relevant event that informs a class instance that the stored property value needs to be changed. Une autre approche consiste à lier les propriétés de dépendance en utilisant des rappels associés PropertyChangedCallback et CoerceValueCallback dans le cadre des métadonnées de ces propriétés lors de l’inscription.Another approach is to tie dependency properties together by using paired PropertyChangedCallback and CoerceValueCallback callbacks as part of those properties' metadata during registration.

Étant donné que le DependencyPropertyKey est privé et qu’il n’est pas propagé par le système de propriétés en dehors de votre code, une propriété de dépendance en lecture seule offre une meilleure sécurité des paramètres qu’une propriété de dépendance en lecture-écriture.Because the DependencyPropertyKey is private, and is not propagated by the property system outside of your code, a read-only dependency property does have better setting security than a read-write dependency property. Pour une propriété de dépendance en lecture-écriture, le champ d’identification est explicitement ou implicitement public et la propriété est donc largement définissable.For a read-write dependency property, the identifying field is explicitly or implicitly public and thus the property is widely settable. Pour plus d’informations, consultez Sécurité de propriété de dépendance.For more specifics, see Dependency Property Security.

Voir aussiSee also