Export (0) Print
Expand All

CacheRequest Class

Specifies properties and patterns that the UI Automation framework caches when an AutomationElement is obtained.

System.Object
  System.Windows.Automation.CacheRequest

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

public sealed class CacheRequest

The CacheRequest type exposes the following members.

  NameDescription
Public methodCacheRequestInitializes a new instance of the CacheRequest class.
Top

  NameDescription
Public propertyAutomationElementModeGets or sets a value that specifies whether returned elements should contain full references to the underlying user interface (UI), or only cached information.
Public propertyStatic memberCurrentGets the CacheRequest that is active on the current thread.
Public propertyTreeFilterGets or sets a value specifying the view of the UI Automation element tree to use when caching.
Public propertyTreeScopeGets or sets a value that specifies whether caching is done only for the root of the subtree, or also for its children or descendants.
Top

  NameDescription
Public methodActivateSets this CacheRequest as the active specification for the items that are returned when an AutomationElement is requested on the same thread.
Public methodAdd(AutomationPattern)Adds the specified AutomationPattern identifier to this CacheRequest.
Public methodAdd(AutomationProperty)Adds the specified AutomationProperty identifier to this CacheRequest.
Public methodCloneCreates a copy of this CacheRequest.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodPopRemoves the active CacheRequest from the internal stack for the current thread.
Public methodPushPlaces the CacheRequest on the internal state stack, making it the active request on the current thread.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

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 void CachePropertiesByActivate(AutomationElement elementList)
{
    AutomationElement elementListItem;

    // Set up the request.
    CacheRequest cacheRequest = new CacheRequest();
    cacheRequest.Add(AutomationElement.NameProperty);
    cacheRequest.Add(AutomationElement.IsEnabledProperty);
    cacheRequest.Add(SelectionItemPattern.Pattern);
    cacheRequest.Add(SelectionItemPattern.SelectionContainerProperty);

    // Obtain an element and cache the requested items. 
    using (cacheRequest.Activate())
    {
        Condition cond = new PropertyCondition(AutomationElement.IsSelectionItemPatternAvailableProperty, true);
        elementListItem = elementList.FindFirst(TreeScope.Children, cond);
    }
    // The CacheRequest is now inactive. 

    // Retrieve the cached property and pattern.
    SelectionItemPattern pattern;
    String itemName;
    try
    {
        itemName = elementListItem.Cached.Name;
        pattern = elementListItem.GetCachedPattern(SelectionItemPattern.Pattern) as SelectionItemPattern;
    }
    catch (InvalidOperationException)
    {
        Console.WriteLine("Object was not in cache.");
        return;
    }
    // Alternatively, you can use TryGetCachedPattern to retrieve the cached pattern. 
    object cachedPattern;
    if (true == elementListItem.TryGetCachedPattern(SelectionItemPattern.Pattern, out cachedPattern))
    {
        pattern = cachedPattern as SelectionItemPattern;
    }

    // Specified pattern properties are also in the cache.
    AutomationElement parentList = 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;
}

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="autoElement">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 void CachePropertiesByPush(AutomationElement elementList)
{
    // Set up the request.
    CacheRequest cacheRequest = 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.
    Condition cond = new PropertyCondition(AutomationElement.IsSelectionItemPatternAvailableProperty, true);
    AutomationElement elementListItem = elementList.FindFirst(TreeScope.Children, cond);

    // 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.
    String itemName = elementListItem.Cached.Name;
    SelectionItemPattern pattern = elementListItem.GetCachedPattern(SelectionItemPattern.Pattern) as SelectionItemPattern;

    // The following is an alternative way of retrieving the Name property.
    itemName = elementListItem.GetCachedPropertyValue(AutomationElement.NameProperty) as String;

    // 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. 
    object objName = elementListItem.GetCachedPropertyValue(AutomationElement.NameProperty, true);
    if (objName == AutomationElement.NotSupported)
    {
        itemName = "Unknown";
    }
    else
    {
        itemName = objName as String;
    }

    // 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; ***/
}

.NET Framework

Supported in: 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft