UnsetValue property
Collapse the table of content
Expand the table of content

DependencyProperty.UnsetValue property

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 object UnsetValue { get; }

Property value

Type: System.Object [.NET] | Platform::Object [C++]

The sentinel value for an unset value.


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.

Caution  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.


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;
        return true;

Requirements (Windows 10 device family)

Device family

Universal, introduced version 10.0.10240.0

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0


Windows::UI::Xaml [C++]



Requirements (Windows 8.x and Windows Phone 8.x)

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]


Windows::UI::Xaml [C++]



See also

Custom dependency properties
Dependency properties overview
Data binding in depth



© 2016 Microsoft