Proprietà di dipendenza personalizzateCustom Dependency Properties

Questo argomento descrive le ragioni per cui sviluppatori di applicazioni Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) e autori di componenti potrebbero decidere di creare una proprietà di dipendenza personalizzata e illustra i passaggi dell'implementazione oltre ad alcune opzioni di implementazione in grado di migliorare le prestazioni, l'usabilità o la versatilità della proprietà.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.

PrerequisitiPrerequisites

In questo argomento si presuppongono la conoscenza delle proprietà di dipendenza dal punto di vista di un consumer di proprietà di dipendenza esistenti nelle classi WPFWPF, nonché la lettura dell'argomento Panoramica sulle proprietà di dipendenza.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. Per seguire gli esempi illustrati in questo argomento, è anche necessario conoscere Extensible Application Markup Language (XAML)Extensible Application Markup Language (XAML) e saper scrivere applicazioni WPFWPF.In order to follow the examples in this topic, you should also understand Extensible Application Markup Language (XAML)Extensible Application Markup Language (XAML) and know how to write WPFWPF applications.

Che cos'è una proprietà di dipendenza?What Is a Dependency Property?

È possibile abilitare quella che altrimenti sarebbe una proprietà CLR (Common Language Runtime) per supportare l'applicazione di stili, l'associazione dati, l'ereditarietà, le animazioni e i valori predefiniti implementandola come proprietà di dipendenza.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. Le proprietà di dipendenza sono WPFWPF proprietà registrate Register con il RegisterReadOnlysistema di proprietà DependencyProperty chiamando il metodo (o ) e supportate da un campo dell'identificatore.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. Le proprietà di dipendenza DependencyObject possono essere DependencyObject usate solo WPFWPF dai tipi, ma sono piuttosto WPFWPF elevate nella gerarchia delle classi, pertanto la maggior parte delle classi disponibili in può supportare le proprietà di dipendenza.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. Per ulteriori informazioni sulle proprietà di dipendenza e su alcuni termini e convenzioni usati per descriverle in questo SDK, vedere Cennipreliminari sulle proprietà di dipendenza .For more information about dependency properties and some of the terminology and conventions used for describing them in this SDK, see Dependency Properties Overview.

Esempio di proprietà di dipendenzaExamples of Dependency Properties

Esempi di proprietà di dipendenza WPFWPF implementate Background nelle Width classi includono, Text tra gli altri, la proprietà, la proprietà e la proprietà.Examples of dependency properties that are implemented on WPFWPF classes include the Background property, the Width property, and the Text property, among many others. Ogni proprietà di dipendenza esposta da una classe DependencyProperty dispone di un campo statico pubblico corrispondente di tipo esposto nella stessa classe.Each dependency property exposed by a class has a corresponding public static field of type DependencyProperty exposed on that same class. Si tratta dell'identificatore per la proprietà di dipendenza.This is the identifier for the dependency property. L'identificatore viene denominato mediante la seguente convenzione: nome della proprietà di dipendenza seguito dalla stringa Property.The identifier is named using a convention: the name of the dependency property with the string Property appended to it. Ad esempio, DependencyProperty il campo Background dell'identificatore corrispondente per la proprietà è BackgroundProperty.For example, the corresponding DependencyProperty identifier field for the Background property is BackgroundProperty. L'identificatore archivia le informazioni sulla proprietà di dipendenza come è stata registrata e l'identificatore SetValueviene quindi utilizzato in un secondo momento per altre operazioni che coinvolgono la proprietà di dipendenza, ad esempio la chiamata .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.

Come indicato in Dependency Properties Overview, WPFWPF tutte le proprietà di dipendenza in (ad eccezione della maggior parte delle proprietà associate) sono anche proprietà CLR a causa dell'implementazione "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. Pertanto, dal codice, è possibile ottenere o impostare le proprietà di dipendenza chiamando le funzioni di accesso CLR che definiscono i wrapper nello stesso modo in cui si utilizzerebbero altre proprietà 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. Come consumer di proprietà di dipendenza stabilite, DependencyObject GetValue in SetValuegenere non si utilizzano i metodi e , che sono il punto di connessione al sistema di proprietà sottostante.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. Piuttosto, l'implementazione esistente delle proprietà GetValue SetValue CLR get avrà già chiamato e all'interno delle implementazioni del wrapper e set della proprietà, utilizzando il campo identificatore in modo appropriato.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 l'implementazione di una proprietà di dipendenza personalizzata viene eseguita in modo autonomo, il wrapper verrà definito in modo simile.If you are implementing a custom dependency property yourself, then you will be defining the wrapper in a similar way.

Quando implementare una proprietà di dipendenzaWhen Should You Implement a Dependency Property?

Quando si implementa una proprietà in una classe, DependencyObjectpurché la classe derivi DependencyProperty da , è possibile eseguire il backup della proprietà con un identificatore e quindi renderla una proprietà di dipendenza.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. Trasformare una proprietà in una proprietà di dipendenza non sempre è necessario o appropriato e dipende dalle esigenze dello scenario.Having your property be a dependency property is not always necessary or appropriate, and will depend on your scenario needs. Talvolta è opportuno usare la tecnica normale che consiste nel supportare la proprietà con un campo privato.Sometimes, the typical technique of backing your property with a private field is adequate. Tuttavia, se si vuole che la proprietà supporti una o più delle seguenti funzionalità WPFWPF, è necessario implementarla come proprietà di dipendenza: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:

  • Si vuole che la proprietà possa essere impostata in uno stile.You want your property to be settable in a style. Per altre informazioni, vedere Applicazione di stili e modelli.For more information, see Styling and Templating.

  • Si vuole che la proprietà supporti il data binding.You want your property to support data binding. Per altre informazioni sulle proprietà di dipendenza di data binding, vedere Eseguire l'associazione delle proprietà di due controlli.For more information about data binding dependency properties, see Bind the Properties of Two Controls.

  • Si vuole che la proprietà possa essere impostata con un riferimento di risorsa dinamica.You want your property to be settable with a dynamic resource reference. Per altre informazioni, vedere Risorse XAML.For more information, see XAML Resources.

  • Si vuole ereditare un valore di proprietà automaticamente da un elemento padre nell'albero degli elementi.You want to inherit a property value automatically from a parent element in the element tree. In questo caso, RegisterAttached eseguire la registrazione con il metodo , anche se si crea anche un wrapper di proprietà per l'accesso CLR.In this case, register with the RegisterAttached method, even if you also create a property wrapper for CLR access. Per altre informazioni, vedere Ereditarietà del valore della proprietà.For more information, see Property Value Inheritance.

  • Si vuole che la proprietà sia animata.You want your property to be animatable. Per ulteriori informazioni, consultate Cenni preliminari sull'animazione.For more information, see Animation Overview.

  • Si vuole che il sistema di proprietà segnali quando il valore precedente della proprietà è stato modificato da azioni intraprese dal sistema di proprietà, dall'ambiente o dall'utente oppure tramite la lettura e l'uso degli stili.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. Se si usano i metadati della proprietà, la proprietà può specificare un metodo di callback che verrà richiamato ogni volta il sistema di proprietà determina che il valore della proprietà è stato modificato definitivamente.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 concetto correlato è la coercizione del valore di proprietà.A related concept is property value coercion. Per altre informazioni, vedere Callback e convalida delle proprietà di dipendenza.For more information, see Dependency Property Callbacks and Validation.

  • Si vogliono usare convenzioni di metadati definite usate anche dai processi WPFWPF, ad esempio la segnalazione dell'eventualità che la modifica di un valore di proprietà richieda che il sistema di layout ricomponga gli elementi visivi di 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. Oppure si vogliono usare override di metadati in modo che le classi derivate possano modificare caratteristiche basate sui metadati quali il valore predefinito.Or you want to be able to use metadata overrides so that derived classes can change metadata-based characteristics such as the default value.

  • Si desidera che le proprietà di un controllo personalizzato ricevano il supporto di Progettazione WPF di Visual Studio, ad esempio la modifica della finestra Proprietà.You want properties of a custom control to receive Visual Studio WPF Designer support, such as Properties window editing.You want properties of a custom control to receive Visual Studio WPF Designer support, such as Properties window editing. Per altre informazioni, vedere Cenni preliminari sulla modifica di controlli.For more information, see Control Authoring Overview.

Quando si esaminano questi scenari, è necessario considerare anche se è possibile realizzare lo scenario eseguendo l'override dei metadati di una proprietà di dipendenza esistente, piuttosto che implementando una proprietà completamente nuova.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. La praticità di un override di metadati dipende dallo scenario e dalla somiglianza di tale scenario con l'implementazione nelle proprietà di dipendenza WPFWPF esistenti e nelle classi.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. Per altre informazioni sull'override dei metadati nelle proprietà esistenti, vedere Metadati delle proprietà di dipendenza.For more information about overriding metadata on existing properties, see Dependency Property Metadata.

Elenco di controllo per la definizione di una proprietà di dipendenzaChecklist for Defining a Dependency Property

La definizione di una proprietà di dipendenza include quattro concetti distinti.Defining a dependency property consists of four distinct concepts. Questi concetti non rappresentano necessariamente passaggi rigidi di una procedura, in quanto alcuni di questi finiscono per essere combinati come singole righe di codice nell'implementazione:These concepts are not necessarily strict procedural steps, because some of these end up being combined as single lines of code in the implementation:

  • (Facoltativo) Creare metadati di proprietà per la proprietà di dipendenza.(Optional) Create property metadata for the dependency property.

  • Registrare il nome della proprietà con il sistema di proprietà, specificando un tipo di proprietario e il tipo del valore di proprietà.Register the property name with the property system, specifying an owner type and the type of the property value. Se usati, specificare anche i metadati della proprietà.Also specify the property metadata, if used.

  • Definire DependencyProperty un identificatore come public static readonly campo nel tipo di proprietario.Define a DependencyProperty identifier as a public static readonly field on the owner type.

  • Definire una proprietà "wrapper" CLR il cui nome corrisponde al nome della proprietà di dipendenza.Define a CLR "wrapper" property whose name matches the name of the dependency property. Implementare la proprietà "wrapper" CLR get e set le funzioni di accesso per connettersi con la proprietà di dipendenza che la supporta.Implement the CLR "wrapper" property's get and set accessors to connect with the dependency property that backs it.

Registrazione della proprietà nel sistema di proprietàRegistering the Property with the Property System

Affinché la proprietà sia una proprietà di dipendenza, è necessario registrarla in una tabella gestita dal sistema di proprietà e assegnarle un identificatore univoco usato come qualificatore per le successive operazioni del sistema di proprietà.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. Queste operazioni possono essere operazioni interne o le API del sistema di proprietà che chiamano il codice.These operations might be internal operations, or your own code calling property system APIs. Per registrare la proprietà, chiamare il Register metodo all'interno del corpo della classe (all'interno della classe, ma all'esterno di qualsiasi definizione di 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). Il campo dell'identificatore Register viene fornito anche dalla chiamata al metodo, come valore restituito.The identifier field is also provided by the Register method call, as the return value. Il motivo Register per cui la chiamata viene eseguita all'esterno di public static readonly altre definizioni di membro è perché si utilizza questo valore restituito per assegnare e creare un campo di tipo DependencyProperty come parte della 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. Questo campo diventa l'identificatore per la proprietà di dipendenza.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)))

Convenzioni di denominazione delle proprietà di dipendenzaDependency Property Name Conventions

Esistono convenzioni di denominazione definite relative alle proprietà di dipendenza che è necessario seguire in tutte le circostanze tranne in casi eccezionali.There are established naming conventions regarding dependency properties that you must follow in all but exceptional circumstances.

La proprietà di dipendenza stessa avrà un nome di base, "AquariumGraphic", Registercome in questo esempio, che viene fornito come primo parametro di .The dependency property itself will have a basic name, "AquariumGraphic" as in this example, which is given as the first parameter of Register. Tale nome deve essere univoco all'interno di ogni tipo di registrazione.That name must be unique within each registering type. Le proprietà di dipendenza ereditate tramite tipi di base sono considerate già parte del tipo di registrazione. I nomi delle proprietà ereditate non possono essere registrati nuovamente.Dependency properties inherited through base types are considered to be already part of the registering type; names of inherited properties cannot be registered again. Tuttavia, esiste una tecnica per aggiungere una classe come proprietario di una proprietà di dipendenza persino quando quella proprietà di dipendenza non è ereditata. Per informazioni dettagliate, vedere Metadati delle proprietà di dipendenza.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.

Quando si crea il campo dell'identificatore, denominare questo campo con il nome della proprietà registrata, più il suffisso Property.When you create the identifier field, name this field by the name of the property as you registered it, plus the suffix Property. Questo campo è l'identificatore per la proprietà di dipendenza e SetValue GetValue verrà utilizzato in un secondo momento come input per le chiamate e effettuate nei wrapper, da qualsiasi altro accesso XAMLXAML di codice alla proprietà tramite il proprio codice, da qualsiasi accesso al codice esterno consentito, dal sistema di proprietà e potenzialmente dai processori.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 definizione della proprietà di dipendenza nel corpo della classe costituisce l'implementazione tipica, ma è anche possibile definire una proprietà di dipendenza nel costruttore statico della 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. Questo approccio potrebbe essere utile nel caso in cui siano necessarie più righe di codice per inizializzare la proprietà di dipendenza.This approach might make sense if you need more than one line of code to initialize the dependency property.

Implementazione del "wrapper"Implementing the "Wrapper"

L'implementazione GetValue del get wrapper deve SetValue chiamare set nell'implementazione e nell'implementazione (la chiamata di registrazione originale e il campo sono illustrati anche qui per chiarezza).Your wrapper implementation should call GetValue in the get implementation, and SetValue in the set implementation (the original registration call and field are shown here too for clarity).

In tutte le circostanze tranne in casi GetValue eccezionali, le implementazioni del wrapper devono eseguire solo le azioni e . SetValueIn all but exceptional circumstances, your wrapper implementations should perform only the GetValue and SetValue actions, respectively. La ragione è discussa nell'argomento Caricamento XAML e proprietà di dipendenza.The reason for this is discussed in the topic XAML Loading and Dependency Properties.

Tutte le proprietà di dipendenza pubbliche esistenti fornite nelle classi WPFWPF usano questo semplice modello di implementazione del wrapper. La maggior parte della complessità della modalità di funzionamento delle proprietà di dipendenza è dovuta a un comportamento intrinseco del sistema di proprietà oppure è implementata tramite altri concetti quali la coercizione o i callback di modifica della proprietà mediante i metadati della proprietà.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

Anche in questo caso, per convenzione, il nome della proprietà wrapper deve Register essere uguale al nome scelto e fornito come primo parametro della chiamata che ha registrato la proprietà.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 la proprietà non segue la convenzione, non necessariamente vengono disabilitati tutti i possibili usi, ma si riscontreranno vari problemi rilevanti:If your property does not follow the convention, this does not necessarily disable all possible uses, but you will encounter several notable issues:

  • Determinati aspetti di stili e modelli non funzioneranno.Certain aspects of styles and templates will not work.

  • La maggior parte degli strumenti e delle finestre di progettazione devono basarsi sulle convenzioni di denominazione per serializzare correttamente XAMLXAML o per fornire assistenza relativamente all'ambiente della finestra di progettazione a livello di singola proprietà.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.

  • L'implementazione WPFWPF XAMLXAML corrente del caricatore ignora completamente i wrapper e si basa sulla convenzione di denominazione durante l'elaborazione dei valori degli attributi.The current implementation of the WPFWPF XAMLXAML loader bypasses the wrappers entirely, and relies on the naming convention when processing attribute values. Per altre informazioni, vedere Caricamento XAML e proprietà di dipendenza.For more information, see XAML Loading and Dependency Properties.

Metadati della proprietà per una nuova proprietà di dipendenzaProperty Metadata for a New Dependency Property

Quando si registra una proprietà di dipendenza, la registrazione tramite il sistema di proprietà crea un oggetto dei metadati che archivia le caratteristiche della proprietà.When you register a dependency property, the registration through the property system creates a metadata object that stores property characteristics. Molte di queste caratteristiche hanno valori predefiniti che vengono impostati Registerse la proprietà è registrata con le semplici firme di .Many of these characteristics have defaults that are set if the property is registered with the simple signatures of Register. Altre firme di consentono di Register specificare i metadati desiderati durante la registrazione della proprietà.Other signatures of Register allow you to specify the metadata that you want as you register the property. I metadati più comuni per le proprietà di dipendenza consistono nel fornire a tali proprietà un valore predefinito che viene applicato alle nuove istanze che usano la proprietà.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 si crea una proprietà di dipendenza esistente FrameworkElementin una classe derivata FrameworkPropertyMetadata di , PropertyMetadata è possibile utilizzare la classe di metadati più specializzata anziché la classe base.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. Il costruttore FrameworkPropertyMetadata per la classe dispone di diverse firme in cui è possibile specificare varie caratteristiche dei metadati in combinazione.The constructor for the FrameworkPropertyMetadata class has several signatures where you can specify various metadata characteristics in combination. Se si desidera specificare solo il valore predefinito, utilizzare Objectla firma che accetta un singolo parametro di tipo .If you want to specify the default value only, use the signature that takes a single parameter of type Object. Passare tale parametro dell'oggetto come valore predefinito specifico del tipo per la propertyType proprietà (il valore predefinito fornito deve essere il tipo fornito come parametro nella Register chiamata).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).

Per FrameworkPropertyMetadata, è anche possibile specificare i flag di opzione dei metadati per la proprietà.For FrameworkPropertyMetadata, you can also specify metadata option flags for your property. Questi flag vengono convertiti in proprietà discrete nei metadati della proprietà dopo la registrazione e usati per comunicare determinate istruzioni condizionali agli altri processi quali il motore di 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.

Impostazione dei flag di metadati appropriatiSetting Appropriate Metadata Flags

  • Se la proprietà (o le modifiche interfaccia utenteuser interface (UI)del relativo valore) influisce sul valore di , e in particolare influisce sul AffectsMeasure AffectsArrangemodo AffectsRenderin cui il sistema di layout deve ridimensionare o eseguire il rendering dell'elemento in una pagina, impostare uno o più dei seguenti flag: , , .If your property (or changes in its value) affects the interfaccia utenteuser 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 che una modifica a questa Interfaccia utenteUI proprietà richiede una modifica al rendering in cui l'oggetto contenitore potrebbe richiedere più o meno spazio all'interno dell'oggetto padre.AffectsMeasure indicates that a change to this property requires a change to Interfaccia utenteUI rendering where the containing object might require more or less space within the parent. Ad esempio, è necessario impostare questo flag per una proprietà "Width".For example, a "Width" property should have this flag set.

    • AffectsArrangeindica che una modifica a questa Interfaccia utenteUI proprietà richiede una modifica al rendering che in genere non richiede una modifica nello spazio dedicato, ma indica che il posizionamento all'interno dello spazio è cambiato.AffectsArrange indicates that a change to this property requires a change to Interfaccia utenteUI rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. Ad esempio, è necessario impostare questo flag per una proprietà "Alignment".For example, an "Alignment" property should have this flag set.

    • AffectsRenderindica che si è verificata un'altra modifica che non influirà sul layout e sulla misura, ma richiede un altro rendering.AffectsRender indicates that some other change has occurred that will not affect layout and measure, but does require another render. Un esempio potrebbe essere una proprietà che modifica un colore di un elemento esistente, ad esempio "Background".An example would be a property that changes a color of an existing element, such as "Background".

    • Questi flag vengono spesso usati come protocollo nei metadati per le implementazioni di override del sistema di proprietà o per i callback del layout.These flags are often used as a protocol in metadata for your own override implementations of property system or layout callbacks. Ad esempio, si OnPropertyChanged potrebbe avere InvalidateArrange un callback che chiamerà se qualsiasi AffectsArrange true proprietà dell'istanza segnala una modifica del valore e ha come nei relativi metadati.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.

  • Alcune proprietà possono influire sulle caratteristiche di rendering dell'elemento padre contenitore, in modo maggiore rispetto alle modifiche nelle dimensioni necessarie indicate in precedenza.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 esempio MinOrphanLines è la proprietà utilizzata nel modello di documento dinamico, in cui le modifiche apportate a tale proprietà possono modificare il rendering complessivo del documento dinamico che contiene il paragrafo.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. Utilizzare AffectsParentArrange AffectsParentMeasure o identificare casi simili nelle proprie proprietà.Use AffectsParentArrange or AffectsParentMeasure to identify similar cases in your own properties.

  • Per impostazione predefinita, le proprietà di dipendenza supportano il data binding.By default, dependency properties support data binding. È possibile disabilitare intenzionalmente il data binding per i casi in cui non esiste uno scenario realistico per il data binding o nei quali le prestazioni del data binding per un oggetto di grandi dimensioni viene considerata 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.

  • Per impostazione Mode predefinita, l'associazione OneWaydati per le proprietà di dipendenza ha per impostazione predefinita .By default, data binding Mode for dependency properties defaults to OneWay. È sempre possibile modificare TwoWay l'associazione in modo che sia per ogni istanza di associazione. Per informazioni dettagliate, vedere Specificare la direzione dell'associazione.You can always change the binding to be TwoWay per binding instance; for details, see Specify the Direction of the Binding. Ma come autore della proprietà di dipendenza, è TwoWay possibile scegliere di rendere la proprietà utilizzare la modalità di associazione per impostazione predefinita.But as the dependency property author, you can choose to make the property use TwoWay binding mode by default. Un esempio di una proprietà MenuItem.IsSubmenuOpendi dipendenza esistente è ; lo scenario per questa IsSubmenuOpen proprietà è che la MenuItem logica di impostazione e la composizione di interagire con lo stile di tema predefinito.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. La IsSubmenuOpen logica della proprietà utilizza l'associazione dati in modo nativo per mantenere lo stato della proprietà in base ad altre proprietà di stato e chiamate al metodo.The IsSubmenuOpen property logic uses data binding natively to maintain the state of the property in accordance to other state properties and method calls. Un'altra proprietà TwoWay di esempio TextBox.Textche esegue l'associazione per impostazione predefinita è .Another example property that binds TwoWay by default is TextBox.Text.

  • È anche possibile abilitare l'ereditarietà Inherits della proprietà in una proprietà di dipendenza personalizzata impostando il flag.You can also enable property inheritance in a custom dependency property by setting the Inherits flag. L'ereditarietà della proprietà è utile per uno scenario in cui gli elementi padre e gli elementi figlio hanno una proprietà in comune e avrebbe senso per gli elementi figlio avere quel particolare valore di proprietà impostato sullo stesso valore impostato dall'elemento padre.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. Un esempio di DataContextproprietà ereditabile è , utilizzata per le operazioni di associazione per abilitare l'importante scenario master-dettagli per la presentazione dei dati.An example inheritable property is DataContext, which is used for binding operations to enable the important master-detail scenario for data presentation. Rendendo DataContext ereditabili anche tutti gli elementi figlio ereditano tale contesto dati.By making DataContext inheritable, any child elements inherit that data context also. A causa dell'ereditarietà del valore della proprietà, è possibile specificare un contesto dati alla radice della pagina o dell'applicazione e non è necessario specificarlo di nuovo per i binding in tutti i possibili elementi figlio.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è anche un buon esempio per illustrare che l'ereditarietà esegue l'override del valore predefinito, ma può sempre essere impostata localmente su qualsiasi elemento figlio specifico. Per informazioni dettagliate, consultate Utilizzare il modello Master-Details con dati gerarchici.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. L'ereditarietà del valore della proprietà può incidere negativamente sulle prestazioni e pertanto deve essere usata sporadicamente. Per informazioni dettagliate, vedere Ereditarietà del valore della proprietà.Property value inheritance does have a possible performance cost, and thus should be used sparingly; for details, see Property Value Inheritance.

  • Impostare Journal il flag per indicare se la proprietà di dipendenza deve essere rilevata o utilizzata dai servizi di inserimento nel journal di navigazione.Set the Journal flag to indicate if your dependency property should be detected or used by navigation journaling services. Un esempio SelectedIndex è la proprietà ; qualsiasi elemento selezionato in un controllo di selezione deve essere mantenuto quando si esplora la cronologia di inserimento nel journal.An example is the SelectedIndex property; any item selected in a selection control should be persisted when the journaling history is navigated.

Proprietà di dipendenza di sola letturaRead-Only Dependency Properties

È possibile definire una proprietà di dipendenza di sola lettura.You can define a dependency property that is read-only. Tuttavia, gli scenari in base ai quali è possibile definire la proprietà come proprietà di sola lettura sono piuttosto diversi, allo stesso modo della procedura per registrare queste proprietà con il sistema di proprietà e di quella per esporre l'identificatore.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. Per altre informazioni, vedere Proprietà di dipendenza di sola lettura.For more information, see Read-Only Dependency Properties.

Proprietà di dipendenza di tipo raccoltaCollection-Type Dependency Properties

Le proprietà di dipendenza di tipo di raccolta presentano alcuni problemi di implementazione aggiuntivi che è opportuno considerare.Collection-type dependency properties have some additional implementation issues to consider. Per altri dettagli, vedere Proprietà di dipendenza di tipo raccolta.For details, see Collection-Type Dependency Properties.

Considerazioni sulla sicurezza delle proprietà di dipendenzaDependency Property Security Considerations

Le proprietà di dipendenza devono essere dichiarate come proprietà pubbliche.Dependency properties should be declared as public properties. I campi dell'identificatore delle proprietà di dipendenza devono essere dichiarati come campi statici pubblici.Dependency property identifier fields should be declared as public static fields. Anche se si tenta di dichiarare altri livelli di accesso, ad esempio protected, è sempre possibile accedere a una proprietà di dipendenza tramite l'identificatore in combinazione con le API del sistema di proprietà.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. Anche un campo dell'identificatore protetto è potenzialmente accessibile a causa della creazione LocalValueEnumeratordi report sui metadati o delle API di determinazione del valore che fanno parte del sistema di proprietà, ad esempio .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. Per altre informazioni, vedere Sicurezza delle proprietà di dipendenza.For more information, see Dependency Property Security.

Proprietà di dipendenza e costruttori di classiDependency Properties and Class Constructors

Esiste un principio generale nella programmazione del codice gestito (spesso applicato mediante strumenti di analisi del codice quale FxCop) in base al quale i costruttori di classi non devono chiamare metodi virtuali.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. Il motivo sta nel fatto che i costruttori possono essere chiamati come inizializzazione di base di un costruttore di classe derivato, pertanto l'uso del metodo virtuale tramite il costruttore potrebbe avvenire a uno stato incompleto dell'inizializzazione dell'istanza di oggetto in corso di creazione.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 si deriva da qualsiasi classe DependencyObjectche deriva già da , è necessario tenere presente che il sistema di proprietà stesso chiama ed espone internamente i metodi virtuali.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. Tali metodi virtuali sono parte dei servizi del sistema di proprietà WPFWPF.These virtual methods are part of the WPFWPF property system services. L'esecuzione dell'override dei metodi consente alle classi derivate di partecipare alla determinazione del valore.Overriding the methods enables derived classes to participate in value determination. Per evitare eventuali problemi con l'inizializzazione del runtime, è consigliabile evitare di impostare valori della proprietà di dipendenza all'interno dei costruttori di classi, a meno che non si segua un modello del costruttore molto specifico.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. Per altri dettagli, vedere Modelli di costruttore sicuri per DependencyObject.For details, see Safe Constructor Patterns for DependencyObjects.

Vedere ancheSee also