Assembly: UIAutomationClient (in uiautomationclient.dll)
XML Namespace: http://schemas.microsoft.com/winfx/2006/xaml/presentation
Retrieving properties and patterns through UI Automation requires cross-process calls that can slow down performance. By caching values of proprieties and patterns in a batch operation, you can enhance the performance of your application.
Create a new cache request by calling the class constructor. The request is populated by repeated calls to the Add method.
Only a single CacheRequest can be active. There are two ways to activate a request:
Call Activate on the request. This pushes the request onto the stack, and the request is popped when the object is disposed. To ensure disposal even if an exception is raised, use the return value from Activate within a using block (Using in Microsoft Visual Basic .NET).
Put the request onto the internal stack by calling Push. Only the topmost request on the stack is active, and it must be the next one removed from the stack by Pop. Popping the request deactivates it.
UI Automation elements obtained while the request is active will have cached values for the properties and patterns specified.
The following example shows how to use Activate to cache patterns and properties.
''' <summary> ''' Caches and retrieves properties for a list item by using CacheRequest.Activate. ''' </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 CachePropertiesByActivate(ByVal elementList As AutomationElement) ' Set up the request. Dim myCacheRequest As New CacheRequest() myCacheRequest.Add(AutomationElement.NameProperty) myCacheRequest.Add(AutomationElement.IsEnabledProperty) myCacheRequest.Add(SelectionItemPattern.Pattern) myCacheRequest.Add(SelectionItemPattern.SelectionContainerProperty) Dim elementListItem As AutomationElement ' Obtain an element and cache the requested items. Using myCacheRequest.Activate() Dim myCondition As New PropertyCondition( _ AutomationElement.IsSelectionItemPatternAvailableProperty, True) elementListItem = elementList.FindFirst(TreeScope.Children, myCondition) End Using ' The CacheRequest is now inactive. ' Retrieve the cached property and pattern. Dim pattern As SelectionItemPattern Dim itemName As String Try itemName = elementListItem.Cached.Name pattern = DirectCast(elementListItem.GetCachedPattern(SelectionItemPattern.Pattern), _ SelectionItemPattern) Catch ex As InvalidOperationException Console.WriteLine("Object was not in cache.") Return End Try ' Alternatively, you can use TryGetCachedPattern to retrieve the cached pattern. Dim cachedPattern As Object = Nothing If True = elementListItem.TryGetCachedPattern(SelectionItemPattern.Pattern, cachedPattern) Then pattern = DirectCast(cachedPattern, SelectionItemPattern) End If ' Specified pattern properties are also in the cache. Dim parentList As AutomationElement = pattern.Cached.SelectionContainer ' The following line will raise an exception, because the HelpText property was not cached. '** String itemHelp = elementListItem.Cached.HelpText; ** ' Similarly, pattern properties that were not specified in the CacheRequest cannot be ' retrieved from the cache. This would raise an exception. '** bool selected = pattern.Cached.IsSelected; ** ' This is still a valid call, even though the property is in the cache. ' Of course, the cached value and the current value are not guaranteed to be the same. itemName = elementListItem.Current.Name End Sub 'CachePropertiesByActivate
The following example shows how to use Push and Pop to cache patterns and properties.
''' <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. cacheRequest.Add(AutomationElement.NameProperty) cacheRequest.Add(SelectionItemPattern.Pattern) ' Activate the request. cacheRequest.Push() ' Obtain an element and cache the requested items. Dim myCondition As New PropertyCondition(AutomationElement.IsSelectionItemPatternAvailableProperty, _ True) 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. cacheRequest.Pop() ' 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" Else 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
Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter EditionThe Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.