This documentation is archived and is not being maintained.

CacheRequest.Activate Method

Sets this CacheRequest as the active specification for the items that are returned when an AutomationElement is requested on the same thread.

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

public IDisposable Activate()

Return Value

Type: System.IDisposable
The object that can be used to dispose the CacheRequest.

Using this method is usually preferable to using Push and Pop as a means of activating the CacheRequest. The object is pushed onto the stack when Activate is called, and then popped off when it is disposed. To ensure disposal, place the return value within a using block (Using in Microsoft Visual Basic .NET).

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();

    // 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;
        itemName = elementListItem.Cached.Name;
        pattern = elementListItem.GetCachedPattern(SelectionItemPattern.Pattern) as SelectionItemPattern;
    catch (InvalidOperationException)
        Console.WriteLine("Object was not in cache.");
    // 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;

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003

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

.NET Framework

Supported in: 3.5, 3.0