DependencyProperty.UnsetValue Property

Definition

Namespace:

Windows.UI.Xaml

Specifies a static value that is used by the property system rather than null to indicate that the property exists, but does not have its value set by the property system or by any app code.

public:
 static property Platform::Object ^ UnsetValue { Platform::Object ^ get(); };

static IInspectable UnsetValue();

public static object UnsetValue { get; }

var object = DependencyProperty.unsetValue;

Public Shared ReadOnly Property UnsetValue As Object

Property Value

Object

Platform::Object

IInspectable

The sentinel value for an unset value.

Examples

This example checks for an existing local value with ReadLocalValue. If there is a local value, as indicated by not returning UnsetValue, then the existing local value is removed by calling ClearValue.

public static bool ClearSetProperty(DependencyObject targetObject, DependencyProperty targetDP)
{
    if (targetObject == null || targetDP == null)
    {
        throw new ArgumentNullException();
    }
    object localValue = targetObject.ReadLocalValue(targetDP);
    if (localValue == DependencyProperty.UnsetValue)
    {
        return false;
    }
    else
    {
        targetObject.ClearValue(targetDP);
        return true;
    }
}

Public Shared Function ClearSetProperty(targetObject As DependencyObject, targetDP As DependencyProperty) As Boolean
    If targetObject Is Nothing Or targetDP Is Nothing Then
        Throw New ArgumentNullException()
    End If
    Dim localValue As Object = targetObject.ReadLocalValue(targetDP)
    If localValue = DependencyProperty.UnsetValue Then
        ClearSetProperty = False
    Else
        targetObject.ClearValue(targetDP)
        ClearSetProperty = True
    End If
End Function

Remarks

UnsetValue is a sentinel value that is used for scenarios where the dependency property system is unable to determine a requested dependency property value. UnsetValue is used rather than null, because null is a valid property value for most reference-type values, and is a frequently used DefaultValue in metadata for a dependency property.

UnsetValue is never returned out of a DependencyObject.GetValue call. When you call DependencyObject.GetValue for a dependency property, one of these conditions is always true:

• A dependency property has a default value established in metadata and that value is returned. This value might come from the property metadata's DefaultValue. This might be null.
• Some other value was established through value precedence (for example a style was applied, or a Binding was evaluated), and the default value is no longer relevant. Even though specifically set, this still might be null. For more info on value precedence, see Dependency properties overview.

DependencyObject.ReadLocalValue returns UnsetValue when the requested property has not been locally set.

Note

Do not register a dependency property with the default value of UnsetValue. This will be confusing for property consumers and will have unintended consequences within the property system.

UnsetValue should be returned from an IValueConverter implementation that provides conversion in a data binding to a dependency property, in any case where the converter is unable to convert a source value. Converters shouldn't throw exceptions for that case in IValueConverter.Convert, these will surface as run-time exceptions that you'd need to add handling for in UnhandledException or worse yet appear to users as actual run-time exceptions. Converter implementations should follow the general binding pattern that any failed binding does nothing and does not provide a value, and UnsetValue rather than null is the sentinel value for that case that the binding engine understands. For more info, see Data binding in depth.

See also

• Convert(Object, TypeName, Object, String)
• Custom dependency properties
• Dependency properties overview
• Data binding in depth