Información general sobre propiedades asociadasAttached Properties Overview

Una propiedad adjunta es un concepto definido por XAML.An attached property is a concept defined by XAML. Una propiedad adjunta está destinada a usarse como un tipo de propiedad global que se puede establecer en cualquier objeto.An attached property is intended to be used as a type of global property that is settable on any object. En Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF), las propiedades adjuntas se definen normalmente como una forma especializada de propiedad de dependencia que no tiene el "contenedor" de propiedades convencional.In Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF), attached properties are typically defined as a specialized form of dependency property that does not have the conventional property "wrapper".

Requisitos previos Prerequisites

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 Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) y que ha leído 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 Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) classes, and have read the Dependency Properties Overview. Para seguir los ejemplos de este tema, también debe entender XAML y saber cómo escribir aplicaciones de WPF.To follow the examples in this topic, you should also understand XAML and know how to write WPF applications.

¿Por qué usar las propiedades adjuntas Why Use Attached Properties

Un objetivo de una propiedad adjunta es permitir que distintos elementos secundarios especifiquen valores únicos para una propiedad que, en realidad, está definida en un elemento primario.One purpose of an attached property is to allow different child elements to specify unique values for a property that is actually defined in a parent element. Una aplicación concreta de este escenario es hacer que los elementos secundarios notifiquen al elemento primario cómo se presentarán en la interfaz de usuario (UI)user interface (UI).A specific application of this scenario is having child elements inform the parent element of how they are to be presented in the interfaz de usuario (UI)user interface (UI). Un ejemplo es el DockPanel.Dock propiedad.One example is the DockPanel.Dock property. El DockPanel.Dock propiedad se crea como una propiedad adjunta porque está diseñado para establecerse en elementos que están dentro de un DockPanel, en lugar de en DockPanel propio.The DockPanel.Dock property is created as an attached property because it is designed to be set on elements that are contained within a DockPanel, rather than on DockPanel itself. El DockPanel clase define estático DependencyProperty campo denominado DockPropertyy, a continuación, se proporciona el GetDock y SetDock métodos como descriptores de acceso públicos para la propiedad adjunta.The DockPanel class defines the static DependencyProperty field named DockProperty, and then provides the GetDock and SetDock methods as public accessors for the attached property.

Propiedades adjuntas en XAML Attached Properties in XAML

En XAML, las propiedades adjuntas se establecen mediante la sintaxis ProveedorDePropiedadAdjunta.NombreDePropiedadIn XAML, you set attached properties by using the syntax AttachedPropertyProvider.PropertyName

El siguiente es un ejemplo de cómo se puede establecer DockPanel.Dock en XAML:The following is an example of how you can set DockPanel.Dock in XAML:

<DockPanel>
  <CheckBox DockPanel.Dock="Top">Hello</CheckBox>
</DockPanel>

Tenga en cuenta que el uso es algo similar a una propiedad estática; siempre se hace referencia el tipo DockPanel que posee y registra la propiedad adjunta, en lugar de hacer referencia a cualquier instancia especificada por nombre.Note that the usage is somewhat similar to a static property; you always reference the type DockPanel that owns and registers the attached property, rather than referring to any instance specified by name.

Además, dado que una propiedad adjunta en XAML es un atributo que se establece en el marcado, solamente la operación set tiene alguna relevancia.Also, because an attached property in XAML is an attribute that you set in markup, only the set operation has any relevance. No se puede obtener directamente una propiedad en XAML, aunque hay algunos mecanismos indirectos para comparar valores, como los desencadenadores en estilos (para obtener más información, consulte Aplicar estilos y plantillas).You cannot directly get a property in XAML, although there are some indirect mechanisms for comparing values, such as triggers in styles (for details, see Styling and Templating).

Implementación de propiedades adjuntas en WPFAttached Property Implementation in WPF

En Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF), la mayoría de las propiedades adjuntas que existen en los tipos WPF que están relacionadas con la presentación de la interfaz de usuario se implementan como propiedades de dependencia.In Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF), most of the attached properties that exist on WPF types that are related to UI presentation are implemented as dependency properties. Las propiedades adjuntas son un concepto XAML, mientras que las propiedades de dependencia son un concepto WPF.Attached properties are a XAML concept, whereas dependency properties are a WPF concept. Dado que las propiedades de WPF conectado son las propiedades de dependencia, admiten los conceptos de propiedad de dependencia como metadatos de las propiedades y los valores predeterminados de los metadatos de esa propiedad.Because WPF attached properties are dependency properties, they support dependency property concepts such as property metadata, and default values from that property metadata.

Cómo las propiedades adjuntas se utilizan el tipo de propietario How Attached Properties Are Used by the Owning Type

Aunque las propiedades adjuntas se pueden establecer en cualquier objeto, eso no significa automáticamente que establecer la propiedad vaya a producir un resultado tangible ni que otro objeto no pueda usar nunca el valor.Although attached properties are settable on any object, that does not automatically mean that setting the property will produce a tangible result, or that the value will ever be used by another object. Por lo general, las propiedades adjuntas están diseñadas para que los objetos procedentes de una amplia variedad de posibles jerarquías de clases o relaciones lógicas puedan, individualmente, notificar información común del tipo que define la propiedad adjunta.Generally, attached properties are intended so that objects coming from a wide variety of possible class hierarchies or logical relationships can each report common information to the type that defines the attached property. El tipo que define la propiedad adjunta suele seguir uno de estos modelos:The type that defines the attached property typically follows one of these models:

  • El tipo que define la propiedad adjunta está diseñado para poder ser el elemento primario de los elementos que establecerán los valores de la propiedad adjunta.The type that defines the attached property is designed so that it can be the parent element of the elements that will set values for the attached property. A continuación, el tipo itera sus objetos secundarios a través de la lógica interna en alguna estructura de árbol de objetos, obtiene los valores y actúa sobre esos valores de algún modo.The type then iterates its child objects through internal logic against some object tree structure, obtains the values, and acts on those values in some manner.

  • El tipo que define la propiedad adjunta se usará como el elemento secundario de una variedad de posibles elementos primarios y modelos de contenido.The type that defines the attached property will be used as the child element for a variety of possible parent elements and content models.

  • El tipo que define la propiedad adjunta representa un servicio.The type that defines the attached property represents a service. Otros tipos establecen los valores de la propiedad adjunta.Other types set values for the attached property. A continuación, cuando el elemento que establece la propiedad se evalúa en el contexto del servicio, los valores de la propiedad adjunta se obtienen a través de la lógica interna de la clase de servicio.Then, when the element that set the property is evaluated in the context of the service, the attached property values are obtained through internal logic of the service class.

Ejemplo de una propiedad adjunta definida por el elemento primarioAn Example of a Parent-Defined Attached Property

El escenario más típico donde WPF define una propiedad adjunta es cuando un elemento primario es compatible con una colección de elementos secundarios y también implementa un comportamiento donde se notifican individualmente los detalles del comportamiento de cada elemento secundario.The most typical scenario where WPF defines an attached property is when a parent element supports a child element collection, and also implements a behavior where the specifics of the behavior are reported individually for each child element.

DockPanel define el DockPanel.Dock propiedad adjunta, y DockPanel tiene código de nivel de clase como parte de su lógica de representación (específicamente, MeasureOverride y ArrangeOverride).DockPanel defines the DockPanel.Dock attached property, and DockPanel has class-level code as part of its rendering logic (specifically, MeasureOverride and ArrangeOverride). Un DockPanel instancia siempre comprobará si alguno de sus elementos secundarios inmediatos tiene establecido un valor para DockPanel.Dock.A DockPanel instance will always check to see whether any of its immediate child elements have set a value for DockPanel.Dock. Si es así, esos valores se convierten en la entrada de la lógica de representación que se aplica a ese elemento secundario determinado.If so, those values become input for the rendering logic applied to that particular child element. Anidar DockPanel instancias cada tratan sus propias colecciones de elementos secundarios inmediatos, pero ese comportamiento es específico de la implementación a la forma DockPanel procesos DockPanel.Dock valores.Nested DockPanel instances each treat their own immediate child element collections, but that behavior is implementation-specific to how DockPanel processes DockPanel.Dock values. Teóricamente, es posible tener propiedades adjuntas que influyan en los elementos, más allá del elemento primario inmediato.It is theoretically possible to have attached properties that influence elements beyond the immediate parent. Si el DockPanel.Dock propiedad adjunta se establece en un elemento que no tiene ningún DockPanel se genera el elemento primario va a actuar, ningún error o excepción.If the DockPanel.Dock attached property is set on an element that has no DockPanel parent element to act upon it, no error or exception is raised. Esto significa simplemente que se estableció un valor de propiedad global, pero no tiene ningún actual DockPanel primario que podría consumir la información.This simply means that a global property value was set, but it has no current DockPanel parent that could consume the information.

Propiedades adjuntas en código Attached Properties in Code

Las propiedades adjuntas en WPF no tiene el típico CLRCLR métodos "contenedor" para el acceso fácil de obtener o establecer.Attached properties in WPF do not have the typical CLRCLR "wrapper" methods for easy get/set access. Esto se debe a que la propiedad adjunta no forma parte necesariamente del espacio de nombres de CLRCLR para las instancias con la propiedad establecida.This is because the attached property is not necessarily part of the CLRCLR namespace for instances where the property is set. No obstante, un procesador de XAML debe poder establecer esos valores durante el análisis de XAML.However, a XAML processor must be able to set those values when XAML is parsed. Para admitir el uso de una propiedad adjunta efectivo, el tipo de propietario de la propiedad adjunta debe implementar métodos de descriptor de acceso dedicados en el formulario Get_PropertyName_ y Set_PropertyName_.To support an effective attached property usage, the owner type of the attached property must implement dedicated accessor methods in the form Get_PropertyName_ and Set_PropertyName_. Estos métodos de descriptor de acceso dedicados también resultan útiles para obtener o establecer la propiedad adjunta en el código.These dedicated accessor methods are also useful to get or set the attached property in code. Desde una perspectiva del código, una propiedad adjunta se parece a un campo de respaldo, que presenta descriptores de acceso de métodos en lugar de descriptores de acceso de propiedades. Ese campo de respaldo puede existir en cualquier objeto, en lugar de tener que definirse específicamente.From a code perspective, an attached property is similar to a backing field that has method accessors instead of property accessors, and that backing field can exist on any object rather than needing to be specifically defined.

En el ejemplo siguiente se muestra cómo establecer una propiedad adjunta en el código.The following example shows how you can set an attached property in code. En este ejemplo, myCheckBox es una instancia de la CheckBox clase.In this example, myCheckBox is an instance of the CheckBox class.

DockPanel myDockPanel = new DockPanel();
CheckBox myCheckBox = new CheckBox();
myCheckBox.Content = "Hello";
myDockPanel.Children.Add(myCheckBox);
DockPanel.SetDock(myCheckBox, Dock.Top);
Dim myDockPanel As New DockPanel()
Dim myCheckBox As New CheckBox()
myCheckBox.Content = "Hello"
myDockPanel.Children.Add(myCheckBox)
DockPanel.SetDock(myCheckBox, Dock.Top)

Caso de forma similar del XAML, si myCheckBox tenía no ya se ha agregado como un elemento secundario de myDockPanel mediante la tercera línea de código, la cuarta línea de código no generaría una excepción, pero el valor de propiedad no interactuaría con un DockPanel primario y, por tanto, no funcionará.Similar to the XAML case, if myCheckBox had not already been added as a child element of myDockPanel by the third line of code, the fourth line of code would not raise an exception, but the property value would not interact with a DockPanel parent and thus would do nothing. Solo un DockPanel.Dock valor establecido en un elemento secundario combinado con la presencia de un DockPanel elemento primario provocará un comportamiento eficaz en la aplicación representada.Only a DockPanel.Dock value set on a child element combined with the presence of a DockPanel parent element will cause an effective behavior in the rendered application. (En este caso, podría establecer la propiedad adjunta y, luego, adjuntarla al árbol.(In this case, you could set the attached property, then attach to the tree. O bien podría establecer la propiedad adjunta después de adjuntarla al árbol.Or you could attach to the tree then set the attached property. En ambos casos, el resultado es el mismo).Either action order provides the same result.)

Metadatos de propiedad adjunta Attached Property Metadata

Al registrar la propiedad, FrameworkPropertyMetadata se establece para especificar características de la propiedad, por ejemplo, si la propiedad afecta a la representación, medida y así sucesivamente.When registering the property, FrameworkPropertyMetadata is set to specify characteristics of the property, such as whether the property affects rendering, measurement, and so on. Los metadatos de una propiedad adjunta no suelen ser diferentes de los de una propiedad de dependencia.Metadata for an attached property is generally no different than on a dependency property. Si especifica un valor predeterminado de una invalidación en los metadatos de la propiedad adjunta, ese valor se convierte en el valor predeterminado de la propiedad adjunta implícita en las instancias de la clase de invalidación.If you specify a default value in an override to attached property metadata, that value becomes the default value of the implicit attached property on instances of the overriding class. En concreto, su valor predeterminado se notifica si algún proceso consulta el valor de una propiedad adjunta a través del descriptor de acceso del método Get de esa propiedad y especifica una instancia de la clase donde se especificaron los metadatos, y el valor de esa propiedad asociada no estaba establecido.Specifically, your default value is reported if some process queries for the value of an attached property through the Get method accessor for that property, specifying an instance of the class where you specified the metadata, and the value for that attached property was otherwise not set.

Si quiere habilitar la herencia de valores de propiedad en una propiedad, debe utilizar las propiedades adjuntas en lugar de propiedades de dependencia no adjuntas.If you want to enable property value inheritance on a property, you should use attached properties rather than non-attached dependency properties. Para obtener información detallada, consulte Herencia de valores de propiedad.For details, see Property Value Inheritance.

Propiedades adjuntas personalizadas Custom Attached Properties

Cuándo crear una propiedad adjunta When to Create an Attached Property

Puede crear una propiedad adjunta cuando existe una razón para tener una mecanismo de definición de propiedades disponible para clases distintas de la clase que se define.You might create an attached property when there is a reason to have a property setting mechanism available for classes other than the defining class. El escenario más común es el diseño.The most common scenario for this is layout. Ejemplos de propiedades de diseño existentes son DockPanel.Dock, Panel.ZIndex, y Canvas.Top.Examples of existing layout properties are DockPanel.Dock, Panel.ZIndex, and Canvas.Top. El escenario habilitado aquí es que los elementos que existen como elementos secundarios de los elementos que controlan el diseño pueden expresar los requisitos de diseño para sus elementos primarios de diseño individualmente, cada uno de los cuales define un valor de propiedad para el elemento primario definido como una propiedad adjunta.The scenario enabled here is that elements that exist as child elements to layout-controlling elements are able to express layout requirements to their layout parent elements individually, each setting a property value that the parent defined as an attached property.

Otro escenario para usar una propiedad adjunta es cuando la clase representa un servicio y quiere que las clases puedan integrar el servicio de manera más transparente.Another scenario for using an attached property is when your class represents a service, and you want classes to be able to integrate the service more transparently.

Otro escenario es recibir soporte técnico de Visual Studio WPF Designer, como propiedades edición de la ventana.Yet another scenario is 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.

Como mencionamos anteriormente, debe realizar el registro como una propiedad adjunta si quiere usar la herencia de valores de propiedad.As mentioned before, you should register as an attached property if you want to use property value inheritance.

Cómo crear una propiedad adjunta How to Create an Attached Property

Si la clase está definiendo la propiedad adjunta estrictamente para su uso en otros tipos, la clase no tiene que derivar DependencyObject.If your class is defining the attached property strictly for use on other types, then the class does not have to derive from DependencyObject. Pero debe derivar de DependencyObject si sigue el modelo general de WPF de tener la propiedad adjunta también ser una propiedad de dependencia.But you do need to derive from DependencyObject if you follow the overall WPF model of having your attached property also be a dependency property.

Defina la propiedad adjunta como una propiedad de dependencia declarando un public static readonly campo de tipo DependencyProperty.Define your attached property as a dependency property by declaring a public static readonly field of type DependencyProperty. Este campo se define mediante el valor devuelto de la RegisterAttached método.You define this field by using the return value of the RegisterAttached method. El nombre del campo debe coincidir con el nombre de propiedad adjunta, anexado la cadena Property, seguir el patrón establecido de WPF de asignación de nombres de los campos que identifican frente a las propiedades que representan.The field name must match the attached property name, appended with the string Property, to follow the established WPF pattern of naming the identifying fields versus the properties that they represent. El proveedor de propiedades adjuntas debe proporcionar también estático Get_PropertyName_ y Set_PropertyName_ métodos como descriptores de acceso para la propiedad adjunta; si no lo hace esto dará como resultado de la propiedad sistema no podrá usar la propiedad adjunta.The attached property provider must also provide static Get_PropertyName_ and Set_PropertyName_ methods as accessors for the attached property; failing to do this will result in the property system being unable to use your attached property.

Nota

Si se omite el descriptor de acceso de la propiedad adjunta get, enlace de datos en la propiedad no funcionará en las herramientas de diseño, como Visual Studio y Expression Blend.If you omit the attached property's get accessor, data binding on the property will not work in design tools, such as Visual Studio and Expression Blend.

Descriptor de acceso getThe Get Accessor

La firma para el Get_PropertyName_ descriptor de acceso debe ser:The signature for the Get_PropertyName_ accessor must be:

public static object GetPropertyName(object target)

  • El objeto target puede especificarse como un tipo más específico en la implementación.The target object can be specified as a more specific type in your implementation. Por ejemplo, el DockPanel.GetDock método el tipo del parámetro como UIElement, porque la propiedad adjunta solo debe establecerse en UIElement instancias.For example, the DockPanel.GetDock method types the parameter as UIElement, because the attached property is only intended to be set on UIElement instances.

  • El valor devuelto puede especificarse como un tipo más específico en la implementación.The return value can be specified as a more specific type in your implementation. Por ejemplo, el GetDock tipos de método como Dock, porque el valor solo puede establecerse en esa enumeración.For example, the GetDock method types it as Dock, because the value can only be set to that enumeration.

Descriptor de acceso setThe Set Accessor

La firma para el Set_PropertyName_ descriptor de acceso debe ser:The signature for the Set_PropertyName_ accessor must be:

public static void SetPropertyName(object target, object value)

  • El objeto target puede especificarse como un tipo más específico en la implementación.The target object can be specified as a more specific type in your implementation. Por ejemplo, el SetDock tipos de método como UIElement, porque la propiedad adjunta solo debe establecerse en UIElement instancias.For example, the SetDock method types it as UIElement, because the attached property is only intended to be set on UIElement instances.

  • El objeto value puede especificarse como un tipo más específico en la implementación.The value object can be specified as a more specific type in your implementation. Por ejemplo, el SetDock tipos de método como Dock, porque el valor solo puede establecerse en esa enumeración.For example, the SetDock method types it as Dock, because the value can only be set to that enumeration. Recuerde que el valor de este método es la entrada procedente del cargador de XAML cuando encuentra la propiedad adjunta en el uso de propiedades adjuntas en un marcado.Remember that the value for this method is the input coming from the XAML loader when it encounters your attached property in an attached property usage in markup. Esa entrada es el valor especificado como un valor de atributo XAML en el marcado.That input is the value specified as a XAML attribute value in markup. Por lo tanto, debe existir compatibilidad con la conversión de tipos, el serializador de valores o la extensión de marcado para el tipo que usa, de modo que el tipo adecuado se pueda crear desde el valor del atributo (que, básicamente, es una cadena).Therefore there must be type conversion, value serializer, or markup extension support for the type you use, such that the appropriate type can be created from the attribute value (which is ultimately just a string).

El ejemplo siguiente muestra el registro de la propiedad de dependencia (mediante el RegisterAttached método), así como el Get_PropertyName_ y Set_PropertyName_ descriptores de acceso.The following example shows the dependency property registration (using the RegisterAttached method), as well as the Get_PropertyName_ and Set_PropertyName_ accessors. En el ejemplo, el nombre de la propiedad adjunta es IsBubbleSource.In the example, the attached property name is IsBubbleSource. Por consiguiente, los descriptores de acceso deben denominarse GetIsBubbleSource y SetIsBubbleSource.Therefore, the accessors must be named GetIsBubbleSource and SetIsBubbleSource.

public static readonly DependencyProperty IsBubbleSourceProperty = DependencyProperty.RegisterAttached(
  "IsBubbleSource",
  typeof(Boolean),
  typeof(AquariumObject),
  new FrameworkPropertyMetadata(false, FrameworkPropertyMetadataOptions.AffectsRender)
);
public static void SetIsBubbleSource(UIElement element, Boolean value)
{
  element.SetValue(IsBubbleSourceProperty, value);
}
public static Boolean GetIsBubbleSource(UIElement element)
{
  return (Boolean)element.GetValue(IsBubbleSourceProperty);
}
Public Shared ReadOnly IsBubbleSourceProperty As DependencyProperty = DependencyProperty.RegisterAttached("IsBubbleSource", GetType(Boolean), GetType(AquariumObject), New FrameworkPropertyMetadata(False, FrameworkPropertyMetadataOptions.AffectsRender))
Public Shared Sub SetIsBubbleSource(ByVal element As UIElement, ByVal value As Boolean)
    element.SetValue(IsBubbleSourceProperty, value)
End Sub
Public Shared Function GetIsBubbleSource(ByVal element As UIElement) As Boolean
    Return CType(element.GetValue(IsBubbleSourceProperty), Boolean)
End Function

Atributos de propiedades adjuntasAttached Property Attributes

WPF define varios Atributos de .NET Framework.NET Framework attributes que están diseñadas para proporcionar información sobre las propiedades adjuntas a los procesos de reflexión y a los usuarios típicos de reflexión y la propiedad de información, tales como diseñadores.WPF defines several Atributos de .NET Framework.NET Framework attributes that are intended to provide information about attached properties to reflection processes, and to typical users of reflection and property information such as designers. Dado que las propiedades adjuntas tienen un tipo de ámbito ilimitado, los diseñadores necesitan una manera de evitar abrumar a los usuarios con una lista global de todas las propiedades adjuntas que se definen en una implementación de tecnología específica que utiliza XAML.Because attached properties have a type of unlimited scope, designers need a way to avoid overwhelming users with a global list of all the attached properties that are defined in a particular technology implementation that uses XAML. El Atributos de .NET Framework.NET Framework attributes que WPF define para las propiedades adjuntas se pueden usar para delimitar las situaciones donde una determinada propiedad adjunta debe mostrarse en una ventana de propiedades.The Atributos de .NET Framework.NET Framework attributes that WPF defines for attached properties can be used to scope the situations where a given attached property should be shown in a properties window. También puede aplicar estos atributos para sus propias propiedades adjuntas personalizadas.You might consider applying these attributes for your own custom attached properties also. El propósito y la sintaxis de Atributos de .NET Framework.NET Framework attributes se describe en las páginas de referencia correspondientes:The purpose and syntax of the Atributos de .NET Framework.NET Framework attributes is described on the appropriate reference pages:

Obtener más información sobre las propiedades adjuntas Learning More About Attached Properties

  • Para obtener más información acerca de cómo crear una propiedad adjunta, consulte Registrar una propiedad asociada.For more information on creating an attached property, see Register an Attached Property.

  • Para obtener escenarios de uso más avanzados sobre las propiedades de dependencia y las propiedades adjuntas, consulte Propiedades de dependencia personalizadas.For more advanced usage scenarios for dependency properties and attached properties, see Custom Dependency Properties.

  • Puede registrar una propiedad como una propiedad adjunta y también como una propiedad de dependencia, pero continuar exponiendo las implementaciones de "contenedor".You can also register a property as an attached property, and as a dependency property, but then still expose "wrapper" implementations. En este caso, la propiedad puede establecerse en ese elemento o en cualquier elemento a través de la sintaxis XAML de la propiedad adjunta.In this case, the property can be set either on that element, or on any element through the XAML attached property syntax. Un ejemplo de una propiedad con un escenario adecuado para usos estándar y adjuntos es FrameworkElement.FlowDirection.An example of a property with an appropriate scenario for both standard and attached usages is FrameworkElement.FlowDirection.

Vea tambiénSee also