• Artigo

DependencyObject.SetValue Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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

Namespace:  System.Windows
Assembly:  System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public Sub SetValue ( _
    dp As DependencyProperty, _
    value As Object _
)

public void SetValue(
    DependencyProperty dp,
    Object value
)

Parameters

Exceptions

Exception Condition
ArgumentException

value was not the correct type as registered for the dp property.

Remarks

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

In contrast, to use the managed code version of SetValue, you must provide input of a DependencyProperty object. You would typically get this value from the public static property that serves as a dependency property identifier, available on the same object that owns the dependency property itself. Note that not all properties are dependency properties, which means that the managed code version of SetValue cannot be used to access all possible properties in the managed API for Silverlight (you can only access dependency properties).

For user code, calling SetValue is not typically necessary. Usually, a Silverlight property or a custom dependency property has a CLR property that wraps it, and you can just set the property value through a conventional CLR usage. There are three notable cases where SetValue is used more typically:

  • You are defining a custom dependency property. You will call SetValue as part of defining your own property set accessor for the CLR usage. For details, see Custom Dependency Objects and 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.

  • The DependencyProperty identifier references an attached property (or you are not sure whether it is attached property or a dependency property with a CLR wrapper). Attached properties also have dedicated get and set accessors, which are typically more type-safe, but it still might be more convenient to use SetValue if you already have the identifier.

JavaScript API Notes

The JavaScript implementation of SetValue is notably different, primarily because its first parameter's input type is treated as a name string, not as a DependencyProperty object. You can use the JavaScript SetValue method to set the value of any Silverlight property that is available to the JavaScript API. However, you generally do not need this method to set property values, because all Silverlight properties support a more direct "dotted" property syntax in JavaScript.

Version Notes

Quirks Mode Notes

In Silverlight 3, if SetValue  was called on a property in the middle of an active animation, the result was just for that one tick. SetValue would properly change that value, but on the next tick, the animation would destroy the value. Visually this typically would look as if nothing had happened (the change to the new value would happen so quickly that it would be unnoticeable). The SetValue call did not change the base value of the animation (GetAnimationBaseValue result). When the animation was stopped, it returned to the value that the property had prior to the animation being started. This behavior remains as a quirks mode behavior if your application targets Silverlight 3.

In Silverlight 4 or later, if the value on a property changes in the middle of an active animation, that SetValue  call will modify the base value of the animation. When the animation is stopped, it will return to the new base value set during the animation. This matches the behavior in WPF.

Examples

The following example shows a simple dependency property declaration. A call to SetValue constitutes the entirety of the set accessor implementation for the CLR wrapper of the new dependency property.

public class Fish : Control
{
    public static readonly DependencyProperty SpeciesProperty =
    DependencyProperty.Register(
    "Species",
    typeof(string),
    typeof(Fish), null
    );
    public string Species
    {
        get { return (string)GetValue(SpeciesProperty); }
        set { SetValue(SpeciesProperty, (string)value); }
    }
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.