Propiedades de dependencia personalizadasCustom Dependency Properties

En este tema se describen las razones por las que los autores de componentes y los desarrolladores de aplicaciones de Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) quieren crear la propiedad de dependencia personalizada, y se describen los pasos de implementación y algunas opciones de implementación que pueden mejorar el rendimiento, la facilidad de uso o la versatilidad de la propiedad.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.

Requisitos previosPrerequisites

En este tema, se supone que entiende las propiedades de dependencia desde la perspectiva de un consumidor de propiedades de dependencia existentes en las clases WPFWPF y que ha leído el tema Información general sobre las propiedades de dependencia.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. Para seguir los ejemplos de este tema, también debe comprender Lenguaje XAML (Extensible Application Markup Language)Extensible Application Markup Language (XAML) y saber cómo escribir aplicaciones de WPFWPF.In order to follow the examples in this topic, you should also understand Lenguaje XAML (Extensible Application Markup Language)Extensible Application Markup Language (XAML) and know how to write WPFWPF applications.

¿Qué es una propiedad de dependencia?What Is a Dependency Property?

Puede habilitar lo que, de lo contrario, sería una propiedad Common Language Runtime (CLR)common language runtime (CLR) para que admita la aplicación de estilos, el enlace de datos, la herencia, las animaciones y los valores predeterminados. Para ello, impleméntela como una propiedad de dependencia.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. Las propiedades de dependencia son propiedades que están registradas con el WPFWPF sistema de propiedades mediante una llamada a la Register método (o RegisterReadOnly), y están respaldadas por un DependencyProperty campo identificador.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. Solo se pueden usar las propiedades de dependencia DependencyObject tipos, pero DependencyObject es bastante elevado en el WPFWPF jerarquía de clases, por lo que la mayoría de las clases disponibles en WPFWPF puede admitir propiedades de dependencia.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. Para obtener más información acerca de las propiedades de dependencia, y algunos de los términos y convenciones que se usan para describirlas en este SDKSDK, consulte Información general sobre las propiedades de dependencia.For more information about dependency properties and some of the terminology and conventions used for describing them in this SDKSDK, see Dependency Properties Overview.

Ejemplos de propiedades de dependenciaExamples of Dependency Properties

Ejemplos de propiedades de dependencia que se implementan en WPFWPF clases incluyen el Background propiedad, el Width propiedad y el Text propiedad, entre muchas otras.Examples of dependency properties that are implemented on WPFWPF classes include the Background property, the Width property, and the Text property, among many others. Cada propiedad de dependencia expuesta por una clase tiene un campo estático público correspondiente de tipo DependencyProperty expuesto en esa misma clase.Each dependency property exposed by a class has a corresponding public static field of type DependencyProperty exposed on that same class. Es el identificador de la propiedad de dependencia.This is the identifier for the dependency property. El identificador se denomina mediante una convención: el nombre de la propiedad de dependencia con la cadena Property anexada.The identifier is named using a convention: the name of the dependency property with the string Property appended to it. Por ejemplo, la correspondiente DependencyProperty campo de identificador de la Background propiedad es BackgroundProperty.For example, the corresponding DependencyProperty identifier field for the Background property is BackgroundProperty. El identificador almacena la información sobre la propiedad de dependencia tal como se ha registrado y el identificador se usa posteriormente para otras operaciones relacionadas con la propiedad de dependencia, como la llamada a 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.

Como se mencionó en la Información general sobre las propiedades de dependencia, todas las propiedades de dependencia de WPFWPF (excepto la mayoría de las propiedades adjuntas) también son propiedades de CLRCLR debido a la implementación del "contenedor".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. Por lo tanto, a partir del código, puede obtener o establecer propiedades de dependencia mediante una llamada a los descriptores de acceso de CLRCLR que definen los contenedores de la misma manera que usaría otras propiedades de CLRCLR.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. Como consumidor de propiedades de dependencia establecidas, no utiliza normalmente el DependencyObject métodos GetValue y SetValue, que son el punto de conexión al sistema de propiedades subyacente.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. En su lugar, la implementación existente de la CLRCLR propiedades ya habrá llamado a GetValue y SetValue dentro de la get y set implementaciones de contenedores de la propiedad mediante el campo de identificador adecuadamente .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. Si se está implementando una propiedad de dependencia personalizada, a continuación, estará definiendo el contenedor de forma similar.If you are implementing a custom dependency property yourself, then you will be defining the wrapper in a similar way.

¿Cuándo se debe implementar una propiedad de dependencia?When Should You Implement a Dependency Property?

Cuando implementa una propiedad en una clase, siempre y cuando la clase se deriva de DependencyObject, tiene la opción de respaldar su propiedad con un DependencyProperty identificador y, por tanto, para que sea una propiedad de dependencia.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. Convertir su propiedad en una propiedad de dependencia no es siempre necesario ni adecuado y dependerá de las necesidades del escenario.Having your property be a dependency property is not always necessary or appropriate, and will depend on your scenario needs. A veces, la técnica típica de respaldar la propiedad con un campo privado es adecuada.Sometimes, the typical technique of backing your property with a private field is adequate. Sin embargo, deberá implementar la propiedad como una propiedad de dependencia cada vez que quiera que esta admita una o varias de las siguientes funcionalidades de WPFWPF: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:

  • Quiere que su propiedad se pueda establecer en un estilo.You want your property to be settable in a style. Para obtener más información, consulte Aplicar estilos y plantillas.For more information, see Styling and Templating.

  • Quiere que su propiedad admita el enlace de datos.You want your property to support data binding. Para obtener más información sobre las propiedades de dependencia de enlace de datos, consulte Enlazar las propiedades de dos controles.For more information about data binding dependency properties, see Bind the Properties of Two Controls.

  • Quiere que su propiedad se pueda establecer con una referencia de recurso dinámico.You want your property to be settable with a dynamic resource reference. Para obtener más información, consulte Recursos XAML.For more information, see XAML Resources.

  • Quiere heredar un valor de propiedad automáticamente de un elemento primario del árbol de elementos.You want to inherit a property value automatically from a parent element in the element tree. En este caso, se registre con el RegisterAttached método, aunque también crea un contenedor de propiedad para CLRCLR acceso.In this case, register with the RegisterAttached method, even if you also create a property wrapper for CLRCLR access. Para más información, vea Herencia de valores de propiedad.For more information, see Property Value Inheritance.

  • Quiere que su propiedad se pueda animar.You want your property to be animatable. Para obtener más información, consulte Información general sobre animaciones.For more information, see Animation Overview.

  • Quiere que el sistema de propiedades notifique cualquier cambio en el valor anterior de la propiedad debido a acciones del sistema de propiedades, el entorno o el usuario, o a la lectura y el uso de estilos.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. Al usar los metadatos de la propiedad, la propiedad puede especificar un método de devolución de llamada que se invocará cada vez que el sistema de propiedades determine un cambio definitivo en el valor de la propiedad.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. Un concepto relacionado es la coerción del valor de propiedad.A related concept is property value coercion. Para obtener más información, consulte Devoluciones de llamada y validación de las propiedades de dependencia.For more information, see Dependency Property Callbacks and Validation.

  • Quiere usar convenciones de metadatos establecidas que también se usan en los procesos de WPFWPF, como notificar si un cambio en un valor de propiedad debe exigir que el sistema de diseño recomponga los elementos visuales de un elemento.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. O bien quiere poder usar invalidaciones de metadatos para que las clases derivadas puedan cambiar las características basadas en metadatos, como el valor predeterminado.Or you want to be able to use metadata overrides so that derived classes can change metadata-based characteristics such as the default value.

  • Desea admiten las propiedades de un control personalizado para recibir el Diseñador de WPF de Visual Studio, como propiedades edición de la ventana.You want properties of a custom control to receive Visual Studio WPF Designer support, such as Properties window editing. Para obtener más información, consulte Información general sobre la creación de controles.For more information, see Control Authoring Overview.

Al examinar estos escenarios, también debe considerar si puede obtener su escenario mediante la invalidación de los metadatos de una propiedad de dependencia existente, en lugar de hacerlo a través de la implementación de una propiedad completamente nueva.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. Que una invalidación de metadatos resulte práctica depende de su escenario y del parecido de ese escenario con la implementación en las clases y las propiedades de dependencia existentes de WPFWPF.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. Para obtener más información sobre cómo invalidar los metadatos de las propiedades existentes, consulte Metadatos de las propiedades de dependencia.For more information about overriding metadata on existing properties, see Dependency Property Metadata.

Lista de comprobación para definir una propiedad de dependenciaChecklist for Defining a Dependency Property

La definición de una propiedad de dependencia consta de cuatro conceptos distintos.Defining a dependency property consists of four distinct concepts. Estos conceptos no son necesariamente procedimientos estrictos, ya que algunos de ellos acaban combinándose en una sola línea de código en la implementación:These concepts are not necessarily strict procedural steps, because some of these end up being combined as single lines of code in the implementation:

  • (Opcional) Cree los metadatos de propiedad de la propiedad de dependencia.(Optional) Create property metadata for the dependency property.

  • Registre el nombre de propiedad con el sistema de propiedades, y especifique el tipo de propietario y el tipo de valor de propiedad.Register the property name with the property system, specifying an owner type and the type of the property value. Especifique también los metadatos de la propiedad, si se usan.Also specify the property metadata, if used.

  • Definir un DependencyProperty identificador como un public static readonly campo en el tipo de propietario.Define a DependencyProperty identifier as a public static readonly field on the owner type.

  • Defina una propiedad de "contenedor" CLRCLR cuyo nombre coincida con el nombre de la propiedad de dependencia.Define a CLRCLR "wrapper" property whose name matches the name of the dependency property. Implemente los descriptores de acceso get y set de la propiedad de "contenedor" CLRCLR para establecer la conexión con la propiedad de dependencia que la respalda.Implement the CLRCLR "wrapper" property's get and set accessors to connect with the dependency property that backs it.

Registro de la propiedad con el sistema de propiedadesRegistering the Property with the Property System

Para que la propiedad sea una propiedad de dependencia, debe registrarla en una tabla (de cuyo mantenimiento se encargue el sistema de propiedades) y asignarle un identificador único, que se usará como calificador en operaciones posteriores del sistema de propiedades.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. Estas operaciones podrían ser operaciones internas o su propio código que llama a las API del sistema de propiedades.These operations might be internal operations, or your own code calling property system APIs. Para registrar la propiedad, llame a la Register método dentro del cuerpo de la clase (dentro de la clase, pero fuera de las definiciones de miembros).To register the property, you call the Register method within the body of your class (inside the class, but outside of any member definitions). El campo de identificador también lo proporciona el Register llamada al método, como el valor devuelto.The identifier field is also provided by the Register method call, as the return value. La razón por la que el Register llamada se realiza fuera de otro miembro definiciones es porque este valor devuelto se utiliza para asignar y crear un public static readonly campo de tipo DependencyProperty como parte de la clase.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. Este campo se convierte en el identificador de la propiedad de dependencia.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)))

Convenciones de nombres de las propiedades de dependenciaDependency Property Name Conventions

Existen convenciones de nomenclatura establecidas con respecto a las propiedades de dependencia que se deben seguir en todas las circunstancias, menos en las excepcionales.There are established naming conventions regarding dependency properties that you must follow in all but exceptional circumstances.

La propiedad de dependencia tendrá un nombre básico, "AquariumGraphic" en este ejemplo, que se proporciona como el primer parámetro de Register.The dependency property itself will have a basic name, "AquariumGraphic" as in this example, which is given as the first parameter of Register. Este nombre debe ser único en cada tipo de registro.That name must be unique within each registering type. Las propiedades de dependencia heredadas a través de tipos base ya se consideran parte del tipo de registro; los nombres de las propiedades heredadas no se pueden volver a registrar.Dependency properties inherited through base types are considered to be already part of the registering type; names of inherited properties cannot be registered again. Sin embargo, existe una técnica para agregar una clase como propietaria de una propiedad de dependencia, aunque esa propiedad de dependencia no sea heredada. Para obtener más información, consulte Metadatos de las propiedades de dependencia.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.

Al crear el campo de identificador, asígnele el nombre de la propiedad tal como lo registró, seguido del sufijo Property.When you create the identifier field, name this field by the name of the property as you registered it, plus the suffix Property. Este campo es el identificador de la propiedad de dependencia, y se usará más adelante como entrada para el SetValue y GetValue permiten las llamadas que le permitirán en los contenedores, por cualquier otro código acceso a la propiedad por su propio código, mediante cualquier acceso de código externo , el sistema de propiedades y, posiblemente, los XAMLXAML procesadores.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.

Nota

La definición de la propiedad de dependencia en el cuerpo de la clase es la implementación típica, pero también es posible definir una propiedad de dependencia en el constructor estático de la clase.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. Este enfoque podría tener sentido si necesita más de una línea de código para inicializar la propiedad de dependencia.This approach might make sense if you need more than one line of code to initialize the dependency property.

Implementación del "contenedor"Implementing the "Wrapper"

Debe llamar la implementación del contenedor GetValue en el get implementación, y SetValue en el set implementación (la llamada de registro original y el campo se muestran aquí demasiado para mayor claridad).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).

En circunstancias excepcionales, las implementaciones de contenedores se deben realizar sólo el GetValue y SetValue acciones, respectivamente.In all but exceptional circumstances, your wrapper implementations should perform only the GetValue and SetValue actions, respectively. La razón se explica en el tema Carga de XAML y propiedades de dependencia.The reason for this is discussed in the topic XAML Loading and Dependency Properties.

Todas las propiedades de dependencia públicas existentes que se proporcionan en las clases de WPFWPF usan este modelo de implementación de contenedor simple; gran parte de la complejidad del funcionamiento de las propiedades de dependencia es de manera inherente un comportamiento del sistema de propiedades, o bien se implementa a través de otros conceptos, como la coerción o las devoluciones de llamada de cambio de propiedad a través de los metadatos de la propiedad.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

De nuevo, por convención, el nombre de la propiedad de contenedor debe ser el mismo que el nombre elegido y asignado como primer parámetro de la Register llamada que registró la propiedad.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. Si la propiedad no cumple esta convención, no deshabilitará necesariamente todos los usos posibles, pero encontrará varios problemas importantes:If your property does not follow the convention, this does not necessarily disable all possible uses, but you will encounter several notable issues:

  • Determinados aspectos de los estilos y las plantillas no funcionarán.Certain aspects of styles and templates will not work.

  • La mayoría de las herramientas y los diseñadores deben basarse en las convenciones de nomenclatura para serializar correctamente XAMLXAML, o para proporcionar al entorno del diseñador asistencia para cada propiedad.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.

  • La implementación actual del cargador de WPFWPF XAMLXAML omite completamente los contenedores y se basa en la convención de nomenclatura al procesar los valores de atributo.The current implementation of the WPFWPF XAMLXAML loader bypasses the wrappers entirely, and relies on the naming convention when processing attribute values. Para obtener más información, consulte Carga de XAML y propiedades de dependencia.For more information, see XAML Loading and Dependency Properties.

Metadatos de propiedad de una nueva propiedad de dependenciaProperty Metadata for a New Dependency Property

Al registrar una propiedad de dependencia, el registro a través del sistema de propiedades crea un objeto de metadatos que almacena las características de la propiedad.When you register a dependency property, the registration through the property system creates a metadata object that stores property characteristics. Muchas de estas características tienen valores predeterminados que se establecen si la propiedad se registra con las signaturas simples de Register.Many of these characteristics have defaults that are set if the property is registered with the simple signatures of Register. Otras signaturas de Register le permiten especificar los metadatos que desee al registrar la propiedad.Other signatures of Register allow you to specify the metadata that you want as you register the property. La asignación de metadatos más común para las propiedades de dependencia consiste en asignarles un valor predeterminado, que se aplicará a las nuevas instancias que usen la propiedad.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.

Si va a crear una propiedad de dependencia que existe en una clase derivada de FrameworkElement, puede usar la clase de metadatos más especializada FrameworkPropertyMetadata en lugar de la base de PropertyMetadata clase.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. El constructor para la FrameworkPropertyMetadata clase tiene varias signaturas, donde puede especificar diversas características de los metadatos en combinación.The constructor for the FrameworkPropertyMetadata class has several signatures where you can specify various metadata characteristics in combination. Si desea especificar solo el valor predeterminado, utilice la firma que toma un único parámetro de tipo Object.If you want to specify the default value only, use the signature that takes a single parameter of type Object. Pase dicho parámetro de objeto como un valor predeterminado específico del tipo para la propiedad (el valor predeterminado proporcionado debe ser el tipo que se proporcionó como el propertyType parámetro en el Register llamar).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).

Para FrameworkPropertyMetadata, también puede especificar marcas de opción de metadatos para la propiedad.For FrameworkPropertyMetadata, you can also specify metadata option flags for your property. Estas marcas se convierten en propiedades discretas en los metadatos de propiedad después del registro y se usan para comunicar ciertos determinantes a otros procesos, como el motor de diseño.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.

Establecimiento de marcas de metadatos adecuadasSetting Appropriate Metadata Flags

  • Si su propiedad (o los cambios en su valor) afecta a la interfaz de usuario (UI)user interface (UI), y en particular afecta a cómo el sistema de diseño debe dimensionar o representar su elemento en una página, conjunto de uno o varios de los siguientes indicadores: AffectsMeasure, AffectsArrange, AffectsRender.If your property (or changes in its value) affects the interfaz de usuario (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 indica que un cambio a esta propiedad requiere un cambio en IUUI representación donde el objeto contenedor puede necesitar más o menos espacio dentro del elemento primario.AffectsMeasure indicates that a change to this property requires a change to IUUI rendering where the containing object might require more or less space within the parent. Por ejemplo, una propiedad "Width" debe tener establecida esta marca.For example, a "Width" property should have this flag set.

    • AffectsArrange indica que un cambio a esta propiedad requiere un cambio en IUUI de representación que normalmente no requiere un cambio en el espacio dedicado, pero indica que la posición dentro del espacio ha cambiado.AffectsArrange indicates that a change to this property requires a change to IUUI rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. Por ejemplo, una propiedad "Alignment" debe tener establecida esta marca.For example, an "Alignment" property should have this flag set.

    • AffectsRender indica que ha habido algún otro cambio que no afectará al diseño y la medida, pero se requiere ninguna otra representación.AffectsRender indicates that some other change has occurred that will not affect layout and measure, but does require another render. Un ejemplo sería una propiedad que cambia un color de un elemento existente, como "Background".An example would be a property that changes a color of an existing element, such as "Background".

    • Estas marcas se usan a menudo como un protocolo en los metadatos para sus propias implementaciones de invalidación de las devoluciones de llamada de diseño o del sistema propiedades.These flags are often used as a protocol in metadata for your own override implementations of property system or layout callbacks. Por ejemplo, es posible que tenga un OnPropertyChanged devolución de llamada que se llamará InvalidateArrange si cualquier propiedad de la instancia notifica un cambio de valor y tiene AffectsArrange como true en sus metadatos.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.

  • Algunas propiedades pueden afectar a la representación de características del elemento primario contenedor, más allá de los cambios en el tamaño necesario mencionados anteriormente.Some properties may affect the rendering characteristics of the containing parent element, in ways above and beyond the changes in required size mentioned above. Un ejemplo es el MinOrphanLines propiedad utilizada en el modelo de documentos dinámicos, donde los cambios en esa propiedad pueden cambiar la representación global del documento dinámico que contiene el párrafo.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. Use AffectsParentArrange o AffectsParentMeasure para identificar casos similares en sus propias propiedades.Use AffectsParentArrange or AffectsParentMeasure to identify similar cases in your own properties.

  • De forma predeterminada, las propiedades de dependencia admiten el enlace de datos.By default, dependency properties support data binding. Puede deshabilitar deliberadamente el enlace de datos en aquellos casos en que no exista ningún escenario realista para el enlace de datos, o en que el rendimiento del enlace de datos de un objeto de gran tamaño se reconozca como un problema.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.

  • De forma predeterminada, el enlace de datos Mode predeterminado de las propiedades de dependencia para OneWay.By default, data binding Mode for dependency properties defaults to OneWay. Siempre puede cambiar el enlace se TwoWay por instancia de enlace; para obtener más información, consulte especificar la dirección del enlace.You can always change the binding to be TwoWay per binding instance; for details, see Specify the Direction of the Binding. Pero como autor de la propiedad de dependencia, puede elegir convertir la propiedad use TwoWay modo de enlace predeterminada.But as the dependency property author, you can choose to make the property use TwoWay binding mode by default. Un ejemplo de una propiedad de dependencia existente es MenuItem.IsSubmenuOpen; el escenario de esta propiedad es el IsSubmenuOpen configuración lógica y la composición de MenuItem interactuar con el estilo de tema predeterminado.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. El IsSubmenuOpen lógica de la propiedad utiliza enlace de datos de forma nativa para mantener el estado de la propiedad de acuerdo con otras propiedades de estado y las llamadas a métodos.The IsSubmenuOpen property logic uses data binding natively to maintain the state of the property in accordance to other state properties and method calls. Otro ejemplo de propiedad que se enlaza TwoWay de forma predeterminada es TextBox.Text.Another example property that binds TwoWay by default is TextBox.Text.

  • También puede habilitar la herencia de propiedades en una propiedad de dependencia personalizada estableciendo el Inherits marca.You can also enable property inheritance in a custom dependency property by setting the Inherits flag. La herencia de propiedades resulta útil para un escenario en que los elementos primarios y secundarios tienen una propiedad en común, y tiene sentido para los elementos secundarios que tienen ese valor de propiedad concreto establecido en el mismo valor que el elemento primario.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. Es un ejemplo de propiedad heredable DataContext, que se usa para las operaciones para habilitar el escenario de maestro y detalles importante para la presentación de los datos de enlace.An example inheritable property is DataContext, which is used for binding operations to enable the important master-detail scenario for data presentation. Mediante la realización de DataContext heredable, todos los elementos secundarios heredan ese contexto de datos también.By making DataContext inheritable, any child elements inherit that data context also. Debido a la herencia de valores de propiedad, puede especificar un contexto de datos en la raíz de la aplicación o la página y no es necesario volver a especificarlo para los enlaces de todos los elementos secundarios posibles.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 También es un buen ejemplo para ilustrar que la herencia invalida el valor predeterminado, pero siempre se puede establecer localmente en cualquier elemento secundario determinado; Para obtener más información, consulte usar el patrón principal-detalle con datos jerárquicos.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. La herencia de valores de propiedad puede presentar un costo de rendimiento y, por tanto, debe usarse con moderación. Para obtener más información, consulte Herencia de valores de propiedad.Property value inheritance does have a possible performance cost, and thus should be used sparingly; for details, see Property Value Inheritance.

  • Establecer el Journal marca para indicar si la propiedad de dependencia debe ser detectada o utilizada por los servicios de registro en diario de navegación.Set the Journal flag to indicate if your dependency property should be detected or used by navigation journaling services. Un ejemplo es el SelectedIndex propiedad; los elementos seleccionados en una selección de control se debe conservar cuando se navega el historial de registro en diario.An example is the SelectedIndex property; any item selected in a selection control should be persisted when the journaling history is navigated.

Propiedades de dependencia de sólo lecturaRead-Only Dependency Properties

Es posible definir una propiedad de dependencia que sea de solo lectura.You can define a dependency property that is read-only. Sin embargo, los escenarios para los que podría definir la propiedad como de solo lectura son algo diferentes, del mismo modo que lo es el procedimiento para registrarlos con el sistema de propiedades y exponer el identificador.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. Para obtener más información, consulte Propiedades de dependencia de solo lectura.For more information, see Read-Only Dependency Properties.

Propiedades de dependencia de tipo de colecciónCollection-Type Dependency Properties

Las propiedades de dependencia de tipo de colección presentan algunos problemas de implementación adicionales que se deben tener en cuenta.Collection-type dependency properties have some additional implementation issues to consider. Para obtener más información, consulte Propiedades de dependencia de tipo de colección.For details, see Collection-Type Dependency Properties.

Consideraciones de seguridad de las propiedades de dependenciaDependency Property Security Considerations

Las propiedades de dependencia deben declararse como propiedades públicas.Dependency properties should be declared as public properties. Los campos de identificador de las propiedades de dependencia deben declararse como campos estáticos públicos.Dependency property identifier fields should be declared as public static fields. Aunque intente declarar otros niveles de acceso (como protegidos), una propiedad de dependencia siempre se puede acceder a través del identificador en combinación con las API del sistema de propiedad.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 APIs. Incluso un campo de identificador protegido es potencialmente accesible debido a la determinación de elaboración de informes o el valor de metadatos API que forman parte del sistema de propiedades, como LocalValueEnumerator.Even a protected identifier field is potentially accessible because of metadata reporting or value determination APIs that are part of the property system, such as LocalValueEnumerator. Para obtener más información, consulte Seguridad de las propiedades de dependencia.For more information, see Dependency Property Security.

Propiedades de dependencia y constructores de claseDependency Properties and Class Constructors

Existe un principio general en la programación de código administrado (que suelen aplicar las herramientas de análisis de código, como FxCop), según el cual los constructores de clase no deben llamar a métodos virtuales.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. Esto es debe a que los constructores se pueden llamar como inicialización base de un constructor de clase derivada y la especificación del método virtual a través del constructor puede producirse en un estado de inicialización incompleto de la instancia del objeto que se está construyendo.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. Al derivar de cualquier clase que ya se deriva de DependencyObject, debe tener en cuenta que el propio sistema de propiedades llama y expone internamente los métodos virtuales.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. Estos métodos virtuales forman parte de los servicios del sistema de propiedades WPFWPF.These virtual methods are part of the WPFWPF property system services. La invalidación de los métodos permite que las clases derivadas participen en la determinación del valor.Overriding the methods enables derived classes to participate in value determination. Para evitar posibles problemas con la inicialización en tiempo de ejecución, no debe establecer valores de propiedades de dependencia dentro de los constructores de clase, a menos que siga un patrón de constructor muy específico.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. Para obtener más información, consulte Modelos de constructores seguros para objetos DependencyObject.For details, see Safe Constructor Patterns for DependencyObjects.

Vea tambiénSee also