AutomationElement.GetCachedPropertyValue Method (AutomationProperty, Boolean)


Retrieves the value of the specified property from the cache of this AutomationElement, optionally ignoring any default property.

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

Public Function GetCachedPropertyValue (
	property As AutomationProperty,
	ignoreDefaultValue As Boolean
) As Object


Type: System.Windows.Automation.AutomationProperty

The identifier of the property to retrieve.

Type: System.Boolean

A value that specifies whether a default value should be ignored if the specified property is not supported.

Return Value

Type: System.Object

An object containing the value of the specified property, or NotSupported if the element does not supply a value and ignoreDefaultValue is true.

Exception Condition

The requested property is not in the cache.


The UI for the AutomationElement no longer exists.

GetCachedPropertyValue retrieves the specified property from the cache for the AutomationElement. To retrieve the current property, call GetCurrentPropertyValue.

Passing false in ignoreDefaultValue is equivalent to calling AutomationElement.GetCachedPropertyValue(AutomationProperty).

If the UI Automation provider for the element itself supports the property, the value of the property is returned. Otherwise, if ignoreDefaultValue is false, a default property specified by UI Automation is returned. For information on default properties, see the property identifier fields of AutomationElement, such as AcceleratorKeyProperty.

This method throws an exception if the requested property was not previously cached.

The following example shows how this method can be used to retrieve a cached property.

''' <summary>
''' Caches and retrieves properties for a list item by using CacheRequest.Push.
''' </summary>
''' <param name="elementList">Element from which to retrieve a child element.</param>
''' <remarks>
''' This code demonstrates various aspects of caching. It is not intended to be 
''' an example of a useful method.
''' </remarks>
Private Sub CachePropertiesByPush(ByVal elementList As AutomationElement)
    ' Set up the request.
    Dim cacheRequest As New CacheRequest()

    ' Do not get a full reference to the cached objects, only to their cached properties and patterns.
    cacheRequest.AutomationElementMode = AutomationElementMode.None

    ' Cache all elements, regardless of whether they are control or content elements.
    cacheRequest.TreeFilter = Automation.RawViewCondition

    ' Property and pattern to cache.

    ' Activate the request.

    ' Obtain an element and cache the requested items.
    Dim myCondition As New PropertyCondition(AutomationElement.IsSelectionItemPatternAvailableProperty, _
    Dim elementListItem As AutomationElement = elementList.FindFirst(TreeScope.Children, myCondition)

    ' At this point, you could call another method that creates a CacheRequest and calls Push/Pop.
    ' While that method was retrieving automation elements, the CacheRequest set in this method 
    ' would not be active. 
    ' Deactivate the request.

    ' Retrieve the cached property and pattern.
    Dim itemName As String = elementListItem.Cached.Name
    Dim pattern As SelectionItemPattern = _
        DirectCast(elementListItem.GetCachedPattern(SelectionItemPattern.Pattern), SelectionItemPattern)

    ' The following is an alternative way of retrieving the Name property.
    itemName = CStr(elementListItem.GetCachedPropertyValue(AutomationElement.NameProperty))

    ' This is yet another way, which returns AutomationElement.NotSupported if the element does
    ' not supply a value. If the second parameter is false, a default name is returned.
    Dim objName As Object = elementListItem.GetCachedPropertyValue(AutomationElement.NameProperty, True)
    If objName Is AutomationElement.NotSupported Then
        itemName = "Unknown"
        itemName = CStr(objName)
    End If
    ' The following call raises an exception, because only the cached properties are available, 
    '  as specified by cacheRequest.AutomationElementMode. If AutomationElementMode had its
    '  default value (Full), this call would be valid.
    '** bool enabled = elementListItem.Current.IsEnabled; **

End Sub 'CachePropertiesByPush

.NET Framework
Available since 3.0
Return to top