Callback e convalida delle proprietà di dipendenza (WPF .NET)
Questo articolo descrive come definire una proprietà di dipendenza e implementare i callback delle proprietà di dipendenza. I callback supportano la convalida del valore, la coercizione dei valori e altre logiche necessarie quando un valore della proprietà cambia.
Prerequisiti
L'articolo presuppone una conoscenza di base delle proprietà di dipendenza e che si abbia letto Panoramica delle proprietà di dipendenza. Per seguire gli esempi in questo articolo, è utile se si ha familiarità con Extensible Application Markup Language (XAML) e si sa come scrivere applicazioni WPF.
Callback di convalida-valore
I callback di convalida consentono di verificare se un nuovo valore della proprietà di dipendenza è valido prima che venga applicato dal sistema di proprietà. Questo callback genera un'eccezione se il valore non soddisfa i criteri di convalida.
I callback di convalida-valore possono essere assegnati a una proprietà di dipendenza una sola volta durante la registrazione delle proprietà. Quando si registra una proprietà di dipendenza, è possibile passare un ValidateValueCallback riferimento al Register(String, Type, Type, PropertyMetadata, ValidateValueCallback) metodo . I callback di convalida-valore non fanno parte dei metadati della proprietà e non possono essere sottoposti a override.
Il valore effettivo di una proprietà di dipendenza è il valore applicato. Il valore effettivo viene determinato tramite la precedenza del valore della proprietà quando esistono più input basati su proprietà. Se un callback di convalida-valore viene registrato per una proprietà di dipendenza, il sistema di proprietà richiamerà il callback di convalida-valore alla modifica del valore, passando il nuovo valore come oggetto . All'interno del callback è possibile eseguire di nuovo il cast dell'oggetto valore al tipo registrato con il sistema di proprietà e quindi eseguire la logica di convalida. Il callback restituisce true se il valore è valido per la proprietà ; in caso contrario false, .
Se un callback validate-value restituisce false, viene generata un'eccezione e il nuovo valore non viene applicato. Gli autori di applicazioni devono essere preparati a gestire queste eccezioni. Un uso comune dei callback di convalida-valore consiste nel convalidare i valori di enumerazione o vincolare i valori numerici quando rappresentano misurazioni con limiti. I callback convalidati vengono richiamati dal sistema di proprietà in scenari diversi, tra cui:
- Inizializzazione dell'oggetto, che applica un valore predefinito in fase di creazione.
- Chiamate a livello di codice a SetValue.
- Override dei metadati che specificano un nuovo valore predefinito.
I callback di convalida-valore non hanno un parametro che specifica l'istanza DependencyObject in cui è impostato il nuovo valore. Tutte le istanze di una DependencyObject condivisione condividono lo stesso callback di convalida-valore, quindi non possono essere usate per convalidare scenari specifici dell'istanza. Per ulteriori informazioni, vedere ValidateValueCallback.
Nell'esempio seguente viene illustrato come impedire che una proprietà, tipizzata come Double, sia impostata su PositiveInfinity o NegativeInfinity.
public class Gauge1 : Control
{
public Gauge1() : base() { }
// Register a dependency property with the specified property name,
// property type, owner type, property metadata, and callbacks.
public static readonly DependencyProperty CurrentReadingProperty =
DependencyProperty.Register(
name: "CurrentReading",
propertyType: typeof(double),
ownerType: typeof(Gauge1),
typeMetadata: new FrameworkPropertyMetadata(
defaultValue: double.NaN,
flags: FrameworkPropertyMetadataOptions.AffectsMeasure),
validateValueCallback: new ValidateValueCallback(IsValidReading));
// CLR wrapper with get/set accessors.
public double CurrentReading
{
get => (double)GetValue(CurrentReadingProperty);
set => SetValue(CurrentReadingProperty, value);
}
// Validate-value callback.
public static bool IsValidReading(object value)
{
double val = (double)value;
return !val.Equals(double.NegativeInfinity) &&
!val.Equals(double.PositiveInfinity);
}
}
Public Class Gauge1
Inherits Control
Public Sub New()
MyBase.New()
End Sub
Public Shared ReadOnly CurrentReadingProperty As DependencyProperty =
DependencyProperty.Register(
name:="CurrentReading",
propertyType:=GetType(Double),
ownerType:=GetType(Gauge1),
typeMetadata:=New FrameworkPropertyMetadata(
defaultValue:=Double.NaN,
flags:=FrameworkPropertyMetadataOptions.AffectsMeasure),
validateValueCallback:=New ValidateValueCallback(AddressOf IsValidReading))
Public Property CurrentReading As Double
Get
Return GetValue(CurrentReadingProperty)
End Get
Set(value As Double)
SetValue(CurrentReadingProperty, value)
End Set
End Property
Public Shared Function IsValidReading(value As Object) As Boolean
Dim val As Double = value
Return Not val.Equals(Double.NegativeInfinity) AndAlso
Not val.Equals(Double.PositiveInfinity)
End Function
End Class
public static void TestValidationBehavior()
{
Gauge1 gauge = new();
Debug.WriteLine($"Test value validation scenario:");
// Set allowed value.
gauge.CurrentReading = 5;
Debug.WriteLine($"Current reading: {gauge.CurrentReading}");
try
{
// Set disallowed value.
gauge.CurrentReading = double.PositiveInfinity;
}
catch (ArgumentException e)
{
Debug.WriteLine($"Exception thrown by ValidateValueCallback: {e.Message}");
}
Debug.WriteLine($"Current reading: {gauge.CurrentReading}");
// Current reading: 5
// Exception thrown by ValidateValueCallback: '∞' is not a valid value for property 'CurrentReading'.
// Current reading: 5
}
Public Shared Sub TestValidationBehavior()
Dim gauge As New Gauge1()
Debug.WriteLine($"Test value validation scenario:")
' Set allowed value.
gauge.CurrentReading = 5
Debug.WriteLine($"Current reading: {gauge.CurrentReading}")
Try
' Set disallowed value.
gauge.CurrentReading = Double.PositiveInfinity
Catch e As ArgumentException
Debug.WriteLine($"Exception thrown by ValidateValueCallback: {e.Message}")
End Try
Debug.WriteLine($"Current reading: {gauge.CurrentReading}")
' Current reading: 5
' Exception thrown by ValidateValueCallback: '∞' is not a valid value for property 'CurrentReading'.
' Current reading 5
End Sub
Callback modificati delle proprietà
I callback modificati dalle proprietà notificano quando il valore effettivo di una proprietà di dipendenza è stato modificato.
I callback modificati dalle proprietà fanno parte dei metadati delle proprietà di dipendenza. Se si deriva da una classe che definisce una proprietà di dipendenza o si aggiunge la classe come proprietario di una proprietà di dipendenza, è possibile eseguire l'override dei metadati. Quando si esegue l'override dei metadati, è possibile fornire un nuovo PropertyChangedCallback riferimento. Usare un callback modificato dalla proprietà per eseguire la logica necessaria quando viene modificato un valore della proprietà.
A differenza dei callback validate-value, i callback con modifica delle proprietà hanno un parametro che specifica l'istanza DependencyObject in cui è impostato il nuovo valore. Nell'esempio seguente viene illustrato come un callback modificato dalla proprietà può usare il riferimento all'istanza DependencyObject per attivare callback con valori di coercice.
Callback con valori di coesistenza
I callback con valori coerciti consentono di ricevere notifiche quando il valore effettivo di una proprietà di dipendenza sta per cambiare, in modo da poter modificare il nuovo valore prima che venga applicato. Oltre a essere attivato dal sistema di proprietà, è possibile richiamare callback con valori di coercizione dal codice.
I callback con valori di coeerce fanno parte dei metadati delle proprietà di dipendenza. Se si deriva da una classe che definisce una proprietà di dipendenza o si aggiunge la classe come proprietario di una proprietà di dipendenza, è possibile eseguire l'override dei metadati. Quando si esegue l'override dei metadati, è possibile fornire un riferimento a un nuovo CoerceValueCallbackoggetto . Usare un callback con valori coerciti per valutare i nuovi valori e coercirli quando necessario. Il callback restituisce il valore coercito se si è verificata la coercizione; in caso contrario, restituisce il nuovo valore non modificato.
Analogamente ai callback modificati dalle proprietà, i callback con valori di coercice hanno un parametro che specifica l'istanza DependencyObject in cui è impostato il nuovo valore. L'esempio seguente mostra in che modo un callback con valori di coerci può usare un DependencyObject riferimento all'istanza per comerce i valori delle proprietà.
Nota
Non è possibile forzare i valori predefiniti delle proprietà. Una proprietà di dipendenza ha il valore predefinito impostato per l'inizializzazione dell'oggetto o quando si cancellano altri valori usando ClearValue.
Callback coerce-value e property-changed in combinazione
È possibile creare dipendenze tra proprietà in un elemento, usando callback con valori di coeerce e callback modificati dalle proprietà in combinazione. Ad esempio, le modifiche apportate a una coercizione forzata della proprietà o alla rivalutazione in un'altra proprietà di dipendenza. L'esempio seguente illustra uno scenario comune: tre proprietà di dipendenza che archiviano rispettivamente il valore corrente, il valore minimo e il valore massimo di un elemento dell'interfaccia utente. Se il valore massimo cambia in modo che sia minore del valore corrente, il valore corrente viene quindi impostato sul nuovo valore massimo. Inoltre, se il valore minimo cambia in modo che sia maggiore del valore corrente, il valore corrente viene quindi impostato sul nuovo valore minimo. Nell'esempio, per PropertyChangedCallback il valore corrente richiama in modo esplicito per CoerceValueCallback i valori minimo e massimo.
public class Gauge2 : Control
{
public Gauge2() : base() { }
// Register a dependency property with the specified property name,
// property type, owner type, property metadata, and callbacks.
public static readonly DependencyProperty CurrentReadingProperty =
DependencyProperty.Register(
name: "CurrentReading",
propertyType: typeof(double),
ownerType: typeof(Gauge2),
typeMetadata: new FrameworkPropertyMetadata(
defaultValue: double.NaN,
flags: FrameworkPropertyMetadataOptions.AffectsMeasure,
propertyChangedCallback: new PropertyChangedCallback(OnCurrentReadingChanged),
coerceValueCallback: new CoerceValueCallback(CoerceCurrentReading)
),
validateValueCallback: new ValidateValueCallback(IsValidReading)
);
// CLR wrapper with get/set accessors.
public double CurrentReading
{
get => (double)GetValue(CurrentReadingProperty);
set => SetValue(CurrentReadingProperty, value);
}
// Validate-value callback.
public static bool IsValidReading(object value)
{
double val = (double)value;
return !val.Equals(double.NegativeInfinity) && !val.Equals(double.PositiveInfinity);
}
// Property-changed callback.
private static void OnCurrentReadingChanged(DependencyObject depObj, DependencyPropertyChangedEventArgs e)
{
depObj.CoerceValue(MinReadingProperty);
depObj.CoerceValue(MaxReadingProperty);
}
// Coerce-value callback.
private static object CoerceCurrentReading(DependencyObject depObj, object value)
{
Gauge2 gauge = (Gauge2)depObj;
double currentVal = (double)value;
currentVal = currentVal < gauge.MinReading ? gauge.MinReading : currentVal;
currentVal = currentVal > gauge.MaxReading ? gauge.MaxReading : currentVal;
return currentVal;
}
// Register a dependency property with the specified property name,
// property type, owner type, property metadata, and callbacks.
public static readonly DependencyProperty MaxReadingProperty = DependencyProperty.Register(
name: "MaxReading",
propertyType: typeof(double),
ownerType: typeof(Gauge2),
typeMetadata: new FrameworkPropertyMetadata(
defaultValue: double.NaN,
flags: FrameworkPropertyMetadataOptions.AffectsMeasure,
propertyChangedCallback: new PropertyChangedCallback(OnMaxReadingChanged),
coerceValueCallback: new CoerceValueCallback(CoerceMaxReading)
),
validateValueCallback: new ValidateValueCallback(IsValidReading)
);
// CLR wrapper with get/set accessors.
public double MaxReading
{
get => (double)GetValue(MaxReadingProperty);
set => SetValue(MaxReadingProperty, value);
}
// Property-changed callback.
private static void OnMaxReadingChanged(DependencyObject depObj, DependencyPropertyChangedEventArgs e)
{
depObj.CoerceValue(MinReadingProperty);
depObj.CoerceValue(CurrentReadingProperty);
}
// Coerce-value callback.
private static object CoerceMaxReading(DependencyObject depObj, object value)
{
Gauge2 gauge = (Gauge2)depObj;
double maxVal = (double)value;
return maxVal < gauge.MinReading ? gauge.MinReading : maxVal;
}
// Register a dependency property with the specified property name,
// property type, owner type, property metadata, and callbacks.
public static readonly DependencyProperty MinReadingProperty = DependencyProperty.Register(
name: "MinReading",
propertyType: typeof(double),
ownerType: typeof(Gauge2),
typeMetadata: new FrameworkPropertyMetadata(
defaultValue: double.NaN,
flags: FrameworkPropertyMetadataOptions.AffectsMeasure,
propertyChangedCallback: new PropertyChangedCallback(OnMinReadingChanged),
coerceValueCallback: new CoerceValueCallback(CoerceMinReading)
),
validateValueCallback: new ValidateValueCallback(IsValidReading));
// CLR wrapper with get/set accessors.
public double MinReading
{
get => (double)GetValue(MinReadingProperty);
set => SetValue(MinReadingProperty, value);
}
// Property-changed callback.
private static void OnMinReadingChanged(DependencyObject depObj, DependencyPropertyChangedEventArgs e)
{
depObj.CoerceValue(MaxReadingProperty);
depObj.CoerceValue(CurrentReadingProperty);
}
// Coerce-value callback.
private static object CoerceMinReading(DependencyObject depObj, object value)
{
Gauge2 gauge = (Gauge2)depObj;
double minVal = (double)value;
return minVal > gauge.MaxReading ? gauge.MaxReading : minVal;
}
}
Public Class Gauge2
Inherits Control
Public Sub New()
MyBase.New()
End Sub
' Register a dependency property with the specified property name,
' property type, owner type, property metadata, And callbacks.
Public Shared ReadOnly CurrentReadingProperty As DependencyProperty =
DependencyProperty.Register(
name:="CurrentReading",
propertyType:=GetType(Double),
ownerType:=GetType(Gauge2),
typeMetadata:=New FrameworkPropertyMetadata(
defaultValue:=Double.NaN,
flags:=FrameworkPropertyMetadataOptions.AffectsMeasure,
propertyChangedCallback:=New PropertyChangedCallback(AddressOf OnCurrentReadingChanged),
coerceValueCallback:=New CoerceValueCallback(AddressOf CoerceCurrentReading)),
validateValueCallback:=New ValidateValueCallback(AddressOf IsValidReading))
' CLR wrapper with get/set accessors.
Public Property CurrentReading As Double
Get
Return GetValue(CurrentReadingProperty)
End Get
Set(value As Double)
SetValue(CurrentReadingProperty, value)
End Set
End Property
' Validate-value callback.
Public Shared Function IsValidReading(value As Object) As Boolean
Dim val As Double = value
Return Not val.Equals(Double.NegativeInfinity) AndAlso Not val.Equals(Double.PositiveInfinity)
End Function
' Property-changed callback.
Private Shared Sub OnCurrentReadingChanged(depObj As DependencyObject, e As DependencyPropertyChangedEventArgs)
depObj.CoerceValue(MinReadingProperty)
depObj.CoerceValue(MaxReadingProperty)
End Sub
' Coerce-value callback.
Private Shared Function CoerceCurrentReading(depObj As DependencyObject, value As Object) As Object
Dim gauge As Gauge2 = CType(depObj, Gauge2)
Dim currentVal As Double = value
currentVal = If(currentVal < gauge.MinReading, gauge.MinReading, currentVal)
currentVal = If(currentVal > gauge.MaxReading, gauge.MaxReading, currentVal)
Return currentVal
End Function
Public Shared ReadOnly MaxReadingProperty As DependencyProperty =
DependencyProperty.Register(
name:="MaxReading",
propertyType:=GetType(Double),
ownerType:=GetType(Gauge2),
typeMetadata:=New FrameworkPropertyMetadata(
defaultValue:=Double.NaN,
flags:=FrameworkPropertyMetadataOptions.AffectsMeasure,
propertyChangedCallback:=New PropertyChangedCallback(AddressOf OnMaxReadingChanged),
coerceValueCallback:=New CoerceValueCallback(AddressOf CoerceMaxReading)),
validateValueCallback:=New ValidateValueCallback(AddressOf IsValidReading))
' CLR wrapper with get/set accessors.
Public Property MaxReading As Double
Get
Return GetValue(MaxReadingProperty)
End Get
Set(value As Double)
SetValue(MaxReadingProperty, value)
End Set
End Property
' Property-changed callback.
Private Shared Sub OnMaxReadingChanged(depObj As DependencyObject, e As DependencyPropertyChangedEventArgs)
depObj.CoerceValue(MinReadingProperty)
depObj.CoerceValue(CurrentReadingProperty)
End Sub
' Coerce-value callback.
Private Shared Function CoerceMaxReading(depObj As DependencyObject, value As Object) As Object
Dim gauge As Gauge2 = CType(depObj, Gauge2)
Dim maxVal As Double = value
Return If(maxVal < gauge.MinReading, gauge.MinReading, maxVal)
End Function
' Register a dependency property with the specified property name,
' property type, owner type, property metadata, And callbacks.
Public Shared ReadOnly MinReadingProperty As DependencyProperty =
DependencyProperty.Register(
name:="MinReading",
propertyType:=GetType(Double),
ownerType:=GetType(Gauge2),
typeMetadata:=New FrameworkPropertyMetadata(
defaultValue:=Double.NaN,
flags:=FrameworkPropertyMetadataOptions.AffectsMeasure,
propertyChangedCallback:=New PropertyChangedCallback(AddressOf OnMinReadingChanged),
coerceValueCallback:=New CoerceValueCallback(AddressOf CoerceMinReading)),
validateValueCallback:=New ValidateValueCallback(AddressOf IsValidReading))
' CLR wrapper with get/set accessors.
Public Property MinReading As Double
Get
Return GetValue(MinReadingProperty)
End Get
Set(value As Double)
SetValue(MinReadingProperty, value)
End Set
End Property
' Property-changed callback.
Private Shared Sub OnMinReadingChanged(depObj As DependencyObject, e As DependencyPropertyChangedEventArgs)
depObj.CoerceValue(MaxReadingProperty)
depObj.CoerceValue(CurrentReadingProperty)
End Sub
' Coerce-value callback.
Private Shared Function CoerceMinReading(depObj As DependencyObject, value As Object) As Object
Dim gauge As Gauge2 = CType(depObj, Gauge2)
Dim minVal As Double = value
Return If(minVal > gauge.MaxReading, gauge.MaxReading, minVal)
End Function
End Class
Scenari di callback avanzati
Vincoli e valori desiderati
Se un valore impostato localmente di una proprietà di dipendenza viene modificato tramite coercizione, il valore del set locale non modificato viene mantenuto come valore desiderato. Se la coercizione è basata su altri valori di proprietà, il sistema di proprietà rivaluta dinamicamente la coercizione ogni volta che tali altri valori cambiano. All'interno dei vincoli della coercizione, il sistema di proprietà applicherà un valore più vicino al valore desiderato. Se la condizione di coercizione non viene più applicata, il sistema di proprietà ripristinerà il valore desiderato, presupponendo che non sia attivo alcun valore di precedenza superiore. Nell'esempio seguente viene verificata la coercizione nello scenario valore corrente, valore minimo e valore massimo.
public static void TestCoercionBehavior()
{
Gauge2 gauge = new()
{
// Set initial values.
MinReading = 0,
MaxReading = 10,
CurrentReading = 5
};
Debug.WriteLine($"Test current/min/max values scenario:");
// Current reading is not coerced.
Debug.WriteLine($"Current reading: " +
$"{gauge.CurrentReading} (min: {gauge.MinReading}, max: {gauge.MaxReading})");
// Current reading is coerced to max value.
gauge.MaxReading = 3;
Debug.WriteLine($"Current reading: " +
$"{gauge.CurrentReading} (min: {gauge.MinReading}, max: {gauge.MaxReading})");
// Current reading is coerced, but tracking back to the desired value.
gauge.MaxReading = 4;
Debug.WriteLine($"Current reading: " +
$"{gauge.CurrentReading} (min: {gauge.MinReading}, max: {gauge.MaxReading})");
// Current reading reverts to the desired value.
gauge.MaxReading = 10;
Debug.WriteLine($"Current reading: " +
$"{gauge.CurrentReading} (min: {gauge.MinReading}, max: {gauge.MaxReading})");
// Current reading remains at the desired value.
gauge.MinReading = 5;
gauge.MaxReading = 5;
Debug.WriteLine($"Current reading: " +
$"{gauge.CurrentReading} (min: {gauge.MinReading}, max: {gauge.MaxReading})");
// Current reading: 5 (min=0, max=10)
// Current reading: 3 (min=0, max=3)
// Current reading: 4 (min=0, max=4)
// Current reading: 5 (min=0, max=10)
// Current reading: 5 (min=5, max=5)
}
Public Shared Sub TestCoercionBehavior()
' Set initial values.
Dim gauge As New Gauge2 With {
.MinReading = 0,
.MaxReading = 10,
.CurrentReading = 5
}
Debug.WriteLine($"Test current/min/max values scenario:")
' Current reading is not coerced.
Debug.WriteLine($"Current reading: " &
$"{gauge.CurrentReading} (min={gauge.MinReading}, max={gauge.MaxReading})")
' Current reading is coerced to max value.
gauge.MaxReading = 3
Debug.WriteLine($"Current reading: " &
$"{gauge.CurrentReading} (min={gauge.MinReading}, max={gauge.MaxReading})")
' Current reading is coerced, but tracking back to the desired value.
gauge.MaxReading = 4
Debug.WriteLine($"Current reading: " &
$"{gauge.CurrentReading} (min={gauge.MinReading}, max={gauge.MaxReading})")
' Current reading reverts to the desired value.
gauge.MaxReading = 10
Debug.WriteLine($"Current reading: " &
$"{gauge.CurrentReading} (min={gauge.MinReading}, max={gauge.MaxReading})")
' Current reading remains at the desired value.
gauge.MinReading = 5
gauge.MaxReading = 5
Debug.WriteLine($"Current reading: " &
$"{gauge.CurrentReading} (min={gauge.MinReading}, max={gauge.MaxReading})")
' Current reading: 5 (min=0, max=10)
' Current reading: 3 (min=0, max=3)
' Current reading: 4 (min=0, max=4)
' Current reading: 5 (min=0, max=10)
' Current reading: 5 (min=5, max=5)
End Sub
Gli scenari di dipendenza abbastanza complessi possono verificarsi quando si dispone di più proprietà dipendenti l'una dall'altra in modo circolare. Tecnicamente, non c'è nulla di sbagliato con le dipendenze complesse, ad eccezione del fatto che un numero elevato di valutazioni può ridurre le prestazioni. Inoltre, le dipendenze complesse esposte nell'interfaccia utente potrebbero confondere gli utenti. Trattare PropertyChangedCallback e CoerceValueCallback in modo non ambiguo il più possibile e non vincolare eccessivamente.
Annulla modifiche al valore
Restituendo UnsetValue da , CoerceValueCallbackè possibile rifiutare una modifica del valore della proprietà. Questo meccanismo è utile quando una modifica del valore della proprietà viene avviata in modo asincrono, ma quando viene applicata non è più valida per lo stato dell'oggetto corrente. Un altro scenario potrebbe consistere nell'eliminare in modo selettivo una modifica del valore in base alla posizione in cui è stata originata. Nell'esempio seguente viene CoerceValueCallback chiamato il GetValueSource metodo , che restituisce una ValueSource struttura con un'enumerazione BaseValueSource che identifica l'origine del nuovo valore.
// Coerce-value callback.
private static object CoerceCurrentReading(DependencyObject depObj, object value)
{
// Get value source.
ValueSource valueSource =
DependencyPropertyHelper.GetValueSource(depObj, CurrentReadingProperty);
// Reject any property value change that's a locally set value.
return valueSource.BaseValueSource == BaseValueSource.Local ?
DependencyProperty.UnsetValue : value;
}
' Coerce-value callback.
Private Shared Function CoerceCurrentReading(depObj As DependencyObject, value As Object) As Object
' Get value source.
Dim valueSource As ValueSource =
DependencyPropertyHelper.GetValueSource(depObj, CurrentReadingProperty)
' Reject any property value that's a locally set value.
Return If(valueSource.BaseValueSource = BaseValueSource.Local, DependencyProperty.UnsetValue, value)
End Function
Vedi anche
.NET Desktop feedback