DependencyObject.SetValue method

Sets the local value of a dependency property on a DependencyObject.


Public Sub SetValue(
  dp As DependencyProperty,  
  value As Object 



Type: DependencyProperty

The identifier of the dependency property to set.


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

The new local value.


If the provided value type does not match the type that is declared for the dependency property as it was originally registered, an exception is thrown.

Not all Windows Runtime properties as used by XAML are dependency properties. A DependencyProperty identifier needs to exist and it must be available as a public property of an owning object, typically the object that registered the property.

For app user-code, calling SetValue is not typically necessary. Usually, a Windows Runtime dependency property or a custom dependency property has a conventional property that wraps it, and you can just set the property value through a conventional dotted usage. Cases where you might still use SetValue are:

  • You are defining a custom dependency property. You will call SetValue as part of defining your own property set accessor for a conventional property usage. For more info, see Custom dependency properties.
  • You are defining a callback or are in some other scope where you are already being passed a DependencyProperty identifier, and it is possible that more than one dependency property exists that you might want to interact with in that scope. In these cases it is probably simpler to call SetValue, passing the identifier.


This example shows a simple dependency property declaration. A call to SetValue constitutes the entirety of the set accessor implementation for the property wrapper of the new dependency property. For more examples, see Custom dependency properties.

Public Class Fish
    Inherits Control

    Public Shared ReadOnly SpeciesProperty As DependencyProperty = _
    "Species", _
    GetType(String), _
    GetType(Fish), _
    Public Property Species As String
            Species = CType(GetValue(SpeciesProperty), String)
        End Get
        Set(value As String)
            SetValue(SpeciesProperty, value)
        End Set
    End Property
End Class

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
XAML user and custom controls sample



© 2015 Microsoft