Propriedades de dependência personalizadaCustom Dependency Properties

Este tópico descreve os motivos pelos quais os desenvolvedores de aplicativos e autores de componentes do Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) podem desejar criar uma propriedade de dependência personalizada. Além disso, descreve as etapas de implementação, bem como algumas opções de implementação que podem melhorar o desempenho, a usabilidade ou a versatilidade da propriedade.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.

Pré-requisitosPrerequisites

Este tópico pressupõe que você entenda as propriedades de dependência da perspectiva de um consumidor das propriedades de dependência existentes em classes do WPFWPF e que leu o tópico Visão geral das propriedades de dependência.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 os exemplos deste tópico, você também deve ter noções básicas de XAML (linguagem XAML)Extensible Application Markup Language (XAML) e saber como escrever aplicativos do WPFWPF.In order to follow the examples in this topic, you should also understand XAML (linguagem XAML)Extensible Application Markup Language (XAML) and know how to write WPFWPF applications.

O que é uma propriedade de dependência?What Is a Dependency Property?

Você pode habilitar o que seria uma propriedade de tempo de execução de idioma comum (CLR) para suportar estilo, vinculação de dados, herança, animações e valores padrão, implementando-o como uma propriedade de dependência.You can enable what would otherwise be a common language runtime (CLR) property to support styling, data binding, inheritance, animations, and default values by implementing it as a dependency property. Propriedades de dependência são propriedades que WPFWPF são registradas Register no RegisterReadOnlysistema de propriedades chamando o método (ou ), e que são apoiadas por um 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. As propriedades de dependência DependencyObject podem ser DependencyObject usadas apenas WPFWPF por tipos, mas é bastante alta WPFWPF na hierarquia de classes, de modo que a maioria das classes disponíveis pode suportar propriedades de dependência.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 obter mais informações sobre propriedades de dependência e algumas das terminologias e convenções usadas para descrevê-las neste SDK, consulte Visão Geral das Propriedades de Dependência.For more information about dependency properties and some of the terminology and conventions used for describing them in this SDK, see Dependency Properties Overview.

Exemplos de propriedades de dependênciaExamples of Dependency Properties

Exemplos de propriedades de dependência WPFWPF que são Background implementadas Width nas aulas Text incluem o imóvel, o imóvel e o imóvel, entre muitos outros.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 propriedade de dependência exposta por uma classe tem DependencyProperty um campo estático público correspondente de tipo exposto nessa mesma classe.Each dependency property exposed by a class has a corresponding public static field of type DependencyProperty exposed on that same class. Esse é o identificador da propriedade de dependência.This is the identifier for the dependency property. O identificador é nomeado com uma convenção: o nome da propriedade de dependência com a cadeia de caracteres Property acrescentada a ela.The identifier is named using a convention: the name of the dependency property with the string Property appended to it. Por exemplo, DependencyProperty o campo identificador correspondente para a Background propriedade é BackgroundProperty.For example, the corresponding DependencyProperty identifier field for the Background property is BackgroundProperty. O identificador armazena as informações sobre a propriedade de dependência como ela foi registrada, e o identificador é SetValueentão usado posteriormente para outras operações envolvendo o imóvel de dependência, como o chamado .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 mencionado na visão geral das propriedades de WPFWPF dependência,todas as propriedades de dependência em (exceto as propriedades mais anexadas) também são propriedades CLR devido à implementação do "wrapper".As mentioned in the Dependency Properties Overview, all dependency properties in WPFWPF (except most attached properties) are also CLR properties because of the "wrapper" implementation. Portanto, a partir do código, você pode obter ou definir propriedades de dependência chamando os acessórios CLR que definem os invólucros da mesma maneira que você usaria outras propriedades CLR.Therefore, from code, you can get or set dependency properties by calling CLR accessors that define the wrappers in the same manner that you would use other CLR properties. Como consumidor de propriedades de dependência estabelecidas, você DependencyObject normalmente não usa os métodos GetValue e, SetValueque são o ponto de conexão com o sistema de propriedade subjacente.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. Em vez disso, a implementação existente das GetValue SetValue propriedades get CLR já terá chamado e dentro das implementações e set invólucros da propriedade, utilizando o campo identificador adequadamente.Rather, the existing implementation of the CLR properties will have already called GetValue and SetValue within the get and set wrapper implementations of the property, using the identifier field appropriately. Se estiver implementando uma propriedade de dependência personalizada, você definirá um wrapper de maneira semelhante.If you are implementing a custom dependency property yourself, then you will be defining the wrapper in a similar way.

Quando é necessário implementar uma propriedade de dependência?When Should You Implement a Dependency Property?

Quando você implementa uma propriedade em uma classe, DependencyObjectdesde que sua classe deseme, você tem a opção de apoiar sua propriedade com um DependencyProperty identificador e, assim, torná-la uma propriedade de dependência.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. Transformar a propriedade em uma propriedade de dependência nem sempre é necessário ou apropriado e dependerá das necessidades do cenário.Having your property be a dependency property is not always necessary or appropriate, and will depend on your scenario needs. Às vezes, a técnica típica de dar suporte à propriedade com um campo privado é adequada.Sometimes, the typical technique of backing your property with a private field is adequate. No entanto, você deverá implementar a propriedade como uma propriedade de dependência sempre que desejar que a propriedade dê suporte a uma ou mais das seguintes funcionalidades do 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:

  • Você deseja que a propriedade seja configurável em um estilo.You want your property to be settable in a style. Para obter mais informações, consulte Styling e Templating.For more information, see Styling and Templating.

  • Você deseja que a propriedade dê suporte à vinculação de dados.You want your property to support data binding. Para obter mais informações sobre propriedades de dependência com a vinculação de dados, consulte Associar as propriedades de dois controles.For more information about data binding dependency properties, see Bind the Properties of Two Controls.

  • Você deseja que a propriedade seja configurável com uma referência de recurso dinâmico.You want your property to be settable with a dynamic resource reference. Para obter mais informações, consulte Recursos XAML.For more information, see XAML Resources.

  • Você deseja herdar um valor da propriedade automaticamente de um elemento pai na árvore de elementos.You want to inherit a property value automatically from a parent element in the element tree. Neste caso, registre-se com o RegisterAttached método, mesmo que você também crie um invólucro de propriedade para acesso CLR.In this case, register with the RegisterAttached method, even if you also create a property wrapper for CLR access. Para obter mais informações, consulte Herança do valor da propriedade.For more information, see Property Value Inheritance.

  • Você deseja que a propriedade possa ser animada.You want your property to be animatable. Para obter mais informações, consulte Visão geral da animação.For more information, see Animation Overview.

  • Você deseja que o sistema de propriedades relate quando o valor anterior da propriedade for alterado por ações executadas pelo sistema de propriedades, ambiente ou usuário ou pela leitura e pelo 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. Ao usar metadados de propriedade, a propriedade pode especificar um método de retorno de chamada que será invocado sempre que o sistema de propriedades determinar que o valor da propriedade foi definitivamente alterado.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. Um conceito relacionado é a coerção do valor da propriedade.A related concept is property value coercion. Para obter mais informações, consulte Retornos de chamada da propriedade de dependência e validação.For more information, see Dependency Property Callbacks and Validation.

  • Você deseja usar convenções de metadados estabelecidas que também são usadas por processos do WPFWPF, como relatar se a alteração de um valor da propriedade deve exigir que o sistema de layout recomponha os visuais de um 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. Ou você deseja conseguir usar substituições de metadados para que as classes derivadas possam alterar características baseadas em metadados, como o valor padrão.Or you want to be able to use metadata overrides so that derived classes can change metadata-based characteristics such as the default value.

  • Você deseja propriedades de um controle personalizado para receber suporte visual Studio WPF Designer, como edição de janelas Propriedades.You want properties of a custom control to receive Visual Studio WPF Designer support, such as Properties window editing. Para obter mais informações, consulte Visão geral da criação de controle.For more information, see Control Authoring Overview.

Ao examinar esses cenários, você também deve considerar se pode obter o cenário substituindo os metadados de uma propriedade de dependência existente, em vez de implementar uma propriedade completamente nova.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. Saber se uma substituição de metadados é prática depende do cenário e da semelhança desse cenário com a implementação nas classes e propriedades de dependência existentes do 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 obter mais informações sobre a substituição de metadados em propriedades existentes, consulte Metadados de propriedades de dependência.For more information about overriding metadata on existing properties, see Dependency Property Metadata.

Lista de verificação para definição de uma propriedade de dependênciaChecklist for Defining a Dependency Property

A definição de uma propriedade de dependência consiste em quatro conceitos distintos.Defining a dependency property consists of four distinct concepts. Esses conceitos não são necessariamente etapas de procedimentos estritas, porque alguns deles acabam sendo combinados como linhas de código individuais na implementação: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) Crie metadados de propriedade para a propriedade de dependência.(Optional) Create property metadata for the dependency property.

  • Registre o nome da propriedade no sistema de propriedades, especificando um tipo de proprietário e o tipo do valor da propriedade.Register the property name with the property system, specifying an owner type and the type of the property value. Especifique também os metadados de propriedade, se forem usados.Also specify the property metadata, if used.

  • Defina DependencyProperty um identificador como um public static readonly campo no tipo proprietário.Define a DependencyProperty identifier as a public static readonly field on the owner type.

  • Defina uma propriedade "wrapper" CLR cujo nome corresponda ao nome da propriedade de dependência.Define a CLR "wrapper" property whose name matches the name of the dependency property. Implemente a propriedade e get set os acessórios "wrapper" da CLR para se conectar com a propriedade de dependência que a apoia.Implement the CLR "wrapper" property's get and set accessors to connect with the dependency property that backs it.

Registrando a propriedade no sistema de propriedadesRegistering the Property with the Property System

Para que a propriedade seja uma propriedade de dependência, é necessário registrá-la em uma tabela mantida pelo sistema de propriedades e fornecer a ela um identificador exclusivo, que é usado como o qualificador para operações posteriores do sistema de propriedades.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. Essas operações podem ser operações internas, ou seu próprio código chamando APIs do sistema de propriedade.These operations might be internal operations, or your own code calling property system APIs. Para registrar a propriedade, Register você chama o método dentro do corpo da sua classe (dentro da classe, mas fora de qualquer definição de membro).To register the property, you call the Register method within the body of your class (inside the class, but outside of any member definitions). O campo identificador também é Register fornecido pela chamada do método, como o valor de retorno.The identifier field is also provided by the Register method call, as the return value. A razão Register pela qual a chamada é feita fora de outras definições public static readonly de membros DependencyProperty é porque você usa esse valor de retorno para atribuir e criar um campo de tipo como parte de sua classe.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. Esse campo se torna o identificador da propriedade de dependência.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)))

Convenções de nomenclatura para propriedades de dependênciaDependency Property Name Conventions

Existem convenções de nomenclatura estabelecidas referentes a propriedades de dependência que sempre devem ser seguidas, exceto em circunstâncias excepcionais.There are established naming conventions regarding dependency properties that you must follow in all but exceptional circumstances.

A propriedade de dependência em si terá um nome básico, "AquariumGraphic" como Registerneste exemplo, que é dado como o primeiro parâmetro de .The dependency property itself will have a basic name, "AquariumGraphic" as in this example, which is given as the first parameter of Register. Esse nome deve ser exclusivo dentro de cada tipo de registro.That name must be unique within each registering type. As propriedades de dependência herdadas por meio dos tipos base já são consideradas uma parte do tipo de registro; os nomes das propriedades herdadas não podem ser registrados novamente.Dependency properties inherited through base types are considered to be already part of the registering type; names of inherited properties cannot be registered again. No entanto, há uma técnica para adicionar uma classe como o proprietário de uma propriedade de dependência mesmo quando a propriedade de dependência não é herdada; para obter detalhes, consulte Metadados de propriedades de dependência.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.

Ao criar o campo de identificador, nomeie-o com o nome da propriedade registrado, mais o sufixo 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 é seu identificador para a propriedade de dependência, e SetValue GetValue ele será usado mais tarde como uma entrada para as chamadas e chamadas que você fará nos invólucros, por qualquer outro código de acesso à propriedade por seu próprio código, por qualquer acesso de código externo que você permitir, pelo sistema de propriedade e potencialmente por XAMLXAML processadores.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.

Observação

A definição da propriedade de dependência no corpo da classe é uma implementação típica, mas também é possível definir uma propriedade de dependência no construtor estático da classe.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. Essa abordagem poderá fazer sentido se você precisar de mais de uma linha de código para inicializar a propriedade de dependência.This approach might make sense if you need more than one line of code to initialize the dependency property.

Implementando o “wrapper”Implementing the "Wrapper"

Sua implementação de GetValue invólucro deve chamar na get implementação, e SetValue na set implementação (a chamada de registro original e o campo são mostrados aqui também para clareza).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).

Em todas as circunstâncias excepcionais, suas implementações de invólucro devem executar apenas as GetValue ações e SetValue ações, respectivamente.In all but exceptional circumstances, your wrapper implementations should perform only the GetValue and SetValue actions, respectively. A razão para isso é abordada no tópico Carregamento de XAML e propriedades de dependência.The reason for this is discussed in the topic XAML Loading and Dependency Properties.

Todas as propriedades de dependência públicas existentes fornecidas nas classes do WPFWPF usam esse modelo simples de implementação wrapper; a maior parte da complexidade do funcionamento das propriedades de dependência é inerentemente um comportamento do sistema de propriedades ou é implementada por meio de outros conceitos como coerção ou retornos de chamada de alteração de propriedade por meio de metadados de propriedade.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

Novamente, por convenção, o nome da propriedade do invólucro deve ser o Register mesmo que o nome escolhido e dado como primeiro parâmetro da chamada que registrou o imóvel.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. Se a propriedade não seguir a convenção, isso não necessariamente desabilitará todos os usos possíveis, mas você encontrará vários problemas notáveis:If your property does not follow the convention, this does not necessarily disable all possible uses, but you will encounter several notable issues:

  • Alguns aspectos de estilos e modelos não funcionarão.Certain aspects of styles and templates will not work.

  • A maioria das ferramentas e dos desenvolvedores deve se basear nas convenções de nomenclatura para a serialização correta de XAMLXAML ou para o fornecimento de assistência de ambiente ao designer em um nível por propriedade.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.

  • A implementação WPFWPF XAMLXAML atual do carregador contorna totalmente os invólucros e se baseia na convenção de nomeação ao processar valores de atributos.The current implementation of the WPFWPF XAMLXAML loader bypasses the wrappers entirely, and relies on the naming convention when processing attribute values. Para obter mais informações, consulte Carregamento de XAML e propriedades de dependência.For more information, see XAML Loading and Dependency Properties.

Metadados de propriedade de uma nova propriedade de dependênciaProperty Metadata for a New Dependency Property

Quando uma propriedade de dependência é registrada, o registro cria um objeto de metadados por meio do sistema de propriedades que armazena as características da propriedade.When you register a dependency property, the registration through the property system creates a metadata object that stores property characteristics. Muitas dessas características possuem padrões definidos se a propriedade for Registerregistrada com as assinaturas simples de .Many of these characteristics have defaults that are set if the property is registered with the simple signatures of Register. Outras Register assinaturas permitem que você especifique os metadados que deseja ao registrar a propriedade.Other signatures of Register allow you to specify the metadata that you want as you register the property. Os metadados mais comuns fornecidos para propriedades de dependência são fornecer a elas um valor padrão que é aplicado a novas instâncias que usam a propriedade.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.

Se você está criando uma propriedade de dependência FrameworkElementque existe em uma classe derivada de , você pode usar a classe FrameworkPropertyMetadata de metadados mais especializada em vez da classe base. PropertyMetadataIf 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. O construtor para FrameworkPropertyMetadata a classe tem várias assinaturas onde você pode especificar várias características de metadados em combinação.The constructor for the FrameworkPropertyMetadata class has several signatures where you can specify various metadata characteristics in combination. Se você quiser especificar apenas o valor padrão, use a Objectassinatura que leva um único parâmetro do tipo .If you want to specify the default value only, use the signature that takes a single parameter of type Object. Passe esse parâmetro de objeto como um valor padrão específico do tipo para sua propriedade propertyType (o valor Register padrão fornecido deve ser o tipo fornecido como parâmetro na chamada).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, você também pode especificar sinalizadores de opção de metadados para sua propriedade.For FrameworkPropertyMetadata, you can also specify metadata option flags for your property. Esses sinalizadores são convertidos em propriedades discretas nos metadados de propriedade após o registro e são usados para comunicar alguns condicionais para outros processos como o mecanismo de layout.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.

configurando sinalizadores de metadados apropriadosSetting Appropriate Metadata Flags

  • Se a sua propriedade (ou alterações UI (interface do usuário)user interface (UI)em seu valor) afetar o , e em particular afetar a forma como o AffectsMeasure AffectsArrangesistema AffectsRenderde layout deve dimensionar ou renderizar seu elemento em uma página, defina uma ou mais das seguintes bandeiras: , , .If your property (or changes in its value) affects the UI (interface do usuário)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.

    • AffectsMeasureindica que uma alteração nesta propriedade Interface de UsuárioUI requer uma alteração na renderização onde o objeto que contém pode exigir mais ou menos espaço dentro do pai.AffectsMeasure indicates that a change to this property requires a change to Interface de UsuárioUI rendering where the containing object might require more or less space within the parent. Por exemplo, uma propriedade “Largura” deve ter esse sinalizador definido.For example, a "Width" property should have this flag set.

    • AffectsArrangeindica que uma alteração nesta propriedade Interface de UsuárioUI requer uma alteração na renderização que normalmente não requer uma alteração no espaço dedicado, mas indica que o posicionamento dentro do espaço mudou.AffectsArrange indicates that a change to this property requires a change to Interface de UsuárioUI rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. Por exemplo, uma propriedade “Alinhamento” deve ter esse sinalizador definido.For example, an "Alignment" property should have this flag set.

    • AffectsRenderindica que alguma outra alteração ocorreu que não afetará o layout e a medida, mas requer outra renderização.AffectsRender indicates that some other change has occurred that will not affect layout and measure, but does require another render. Um exemplo seria uma propriedade que altera a cor de um elemento existente, como “Tela de Fundo”.An example would be a property that changes a color of an existing element, such as "Background".

    • Em geral, esses sinalizadores são usados como um protocolo em metadados de suas próprias implementações de substituição do sistema de propriedades ou de retornos de chamada do layout.These flags are often used as a protocol in metadata for your own override implementations of property system or layout callbacks. Por exemplo, você OnPropertyChanged pode ter um InvalidateArrange retorno de chamada que ligará AffectsArrange se true qualquer propriedade da instância relatar uma alteração de valor e tiver como em seus metadados.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.

  • Algumas propriedades podem afetar as características de renderização do elemento pai recipiente, de maneiras que estão além das alterações no espaço necessário mencionado acima.Some properties may affect the rendering characteristics of the containing parent element, in ways above and beyond the changes in required size mentioned above. Um exemplo MinOrphanLines é a propriedade usada no modelo de documento de fluxo, onde alterações nessa propriedade podem alterar a renderização geral do documento de fluxo que contém o parágrafo.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 AffectsParentMeasure ou identifique casos semelhantes em suas próprias propriedades.Use AffectsParentArrange or AffectsParentMeasure to identify similar cases in your own properties.

  • Por padrão, as propriedades de dependência dão suporte à vinculação de dados.By default, dependency properties support data binding. Você pode deliberadamente desabilitar a vinculação de dados, em casos nos quais não haja nenhum cenário realista para a vinculação de dados ou nos quais o desempenho na vinculação de dados de um objeto grande seja reconhecido como um 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.

  • Por padrão, Mode a vinculação de OneWaydados para propriedades de dependência é padrão para .By default, data binding Mode for dependency properties defaults to OneWay. Você sempre pode alterar TwoWay a vinculação para ser por instância vinculante; para obter detalhes, consulte Especificar a direção da vinculação.You can always change the binding to be TwoWay per binding instance; for details, see Specify the Direction of the Binding. Mas como autor da propriedade de dependência, você TwoWay pode optar por fazer com que a propriedade use o modo de vinculação por padrão.But as the dependency property author, you can choose to make the property use TwoWay binding mode by default. Um exemplo de uma propriedade MenuItem.IsSubmenuOpende dependência existente é; o cenário para esta IsSubmenuOpen propriedade é que a lógica MenuItem de configuração e a composição de interagir com o estilo temático padrão.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. A IsSubmenuOpen lógica da propriedade usa a vinculação de dados nativamente para manter o estado da propriedade de acordo com outras propriedades estatais e chamadas de método.The IsSubmenuOpen property logic uses data binding natively to maintain the state of the property in accordance to other state properties and method calls. Outro exemplo de TwoWay propriedade que TextBox.Textse liga por padrão é .Another example property that binds TwoWay by default is TextBox.Text.

  • Você também pode habilitar a herança de Inherits propriedade em uma propriedade de dependência personalizada definindo o sinalizador.You can also enable property inheritance in a custom dependency property by setting the Inherits flag. A herança de propriedade é útil para um cenário em que os elementos pai e filho têm uma propriedade em comum e faz sentido que os elementos filho tenham esse valor da propriedade específico definido com o mesmo valor definido pelo pai.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. Um exemplo de DataContextpropriedade hereditária é, que é usado para operações de vinculação para permitir o importante cenário de detalhes mestres para apresentação de dados.An example inheritable property is DataContext, which is used for binding operations to enable the important master-detail scenario for data presentation. Ao DataContext tornar hereditário, qualquer elemento infantil herda esse contexto de dados também.By making DataContext inheritable, any child elements inherit that data context also. Devido à herança do valor da propriedade, é possível especificar um contexto de dados na página ou na raiz do aplicativo e não é necessário especificá-lo novamente para associações em todos os elementos filho possíveis.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. DataContexttambém é um bom exemplo para ilustrar que a herança substitui o valor padrão, mas sempre pode ser definido localmente em qualquer elemento infantil em particular; para obter detalhes, consulte Usar o padrão de detalhes mestre susciado com dados hierá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. A herança do valor da propriedade tem um possível custo de desempenho e, portanto, deve ser usada com moderação; para obter detalhes, consulte Herança do valor da propriedade.Property value inheritance does have a possible performance cost, and thus should be used sparingly; for details, see Property Value Inheritance.

  • Defina Journal o sinalizador para indicar se sua propriedade de dependência deve ser detectada ou usada por serviços de diário de navegação.Set the Journal flag to indicate if your dependency property should be detected or used by navigation journaling services. Um exemplo SelectedIndex é a propriedade; qualquer item selecionado em um controle de seleção deve ser persistido quando o histórico de diários for navegado.An example is the SelectedIndex property; any item selected in a selection control should be persisted when the journaling history is navigated.

Propriedades de dependência somente leituraRead-Only Dependency Properties

É possível definir uma propriedade de dependência somente leitura.You can define a dependency property that is read-only. No entanto, os cenários para os motivos pelos quais é possível definir a propriedade como somente leitura são um pouco diferentes, assim como o procedimento para registrá-la no sistema de propriedades e expôr o 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 obter mais informações, consulte Propriedades de dependência somente leitura.For more information, see Read-Only Dependency Properties.

Propriedades de dependência do tipo de coleçãoCollection-Type Dependency Properties

As propriedades de dependência do tipo de coleção apresentam algumas outras questões de implementação a serem consideradas.Collection-type dependency properties have some additional implementation issues to consider. Para obter detalhes, consulte Propriedades de dependência do tipo de coleção.For details, see Collection-Type Dependency Properties.

Considerações sobre segurança das propriedades de dependênciaDependency Property Security Considerations

As propriedades de dependência devem ser declaradas como propriedades públicas.Dependency properties should be declared as public properties. Os campos do identificador das propriedades de dependência devem ser declarados como campos estáticos públicos.Dependency property identifier fields should be declared as public static fields. Mesmo se você tentar declarar outros níveis de acesso (como protegidos), uma propriedade de dependência sempre pode ser acessada através do identificador em combinação com as APIs do sistema de propriedade.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. Mesmo um campo identificador protegido é potencialmente acessível devido a relatórios de metadados ou APIs de determinação de valor que fazem parte do sistema de propriedade, tais 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 obter mais informações, consulte Segurança das propriedades de dependência.For more information, see Dependency Property Security.

Propriedades de dependência e construtores de classeDependency Properties and Class Constructors

Há um princípio geral na programação de código gerenciado (frequentemente imposto pelas ferramentas de análise de código como o FxCop) que estabelece que os construtores de classe não devem chamar métodos virtuais.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. Isso ocorre porque os construtores podem ser chamados como a inicialização base de um construtor de classe derivada e a entrada no método virtual por meio do construtor pode ocorrer em um estado de inicialização incompleto da instância do objeto que está sendo construída.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. Quando você deriva de qualquer classe DependencyObjectque já deriva, você deve estar ciente de que o próprio sistema de propriedade chama e expõe métodos virtuais internamente.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. Esses métodos virtuais fazem parte dos serviços do sistema de propriedades do WPFWPF.These virtual methods are part of the WPFWPF property system services. A substituição dos métodos permite que as classes derivadas participem da determinação do valor.Overriding the methods enables derived classes to participate in value determination. Para evitar possíveis problemas com a inicialização em runtime, você não deverá definir valores da propriedade de dependência dentro de construtores de classes, a menos que um padrão de construtor muito específico seja seguido.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 obter detalhes, consulte Padrões de construtor seguros para DependencyObjects.For details, see Safe Constructor Patterns for DependencyObjects.

Confira tambémSee also