共用方式為

使用 UI 自動化中的快取

  • 發行項
注意事項注意事項

這份文件適用於想要使用 System.Windows.Automation 命名空間中定義之 Managed UI Automation 類別的 .NET Framework 開發人員。如需 UI Automation 的最新資訊，請參閱 Windows Automation API：使用者介面自動化 (英文)。

本節說明如何實作 AutomationElement 屬性和控制項模式的快取。

啟動快取要求

  1. 建立 CacheRequest。

  2. 使用 Add 指定要快取的屬性和模式。

  3. 設定 TreeScope 屬性，以指定快取的範圍。

  4. 設定 TreeFilter 屬性，以指定樹狀子目錄的檢視。

  5. 如果要提高效率，可以將 AutomationElementMode 屬性設為 None，不擷取物件的完整參考 (如此將無法從這些物件擷取目前值)。

  6. 在 using 區塊 (Microsoft Visual Basic .NET 中為 Using) 內使用 Activate，啟動要求。

在取得 AutomationElement 物件或訂閱事件之後，使用 Pop (若使用 Push) 或處置 Activate 所建立的物件，以停用要求 (在 using 區塊 (Microsoft Visual Basic .NET 中為 Using) 中使用 Activate)。

快取 AutomationElement 屬性

  1. 當 CacheRequest 在作用中時，使用 FindFirst 或 FindAll 取得 AutomationElement 物件；或取得 AutomationElement 做為 CacheRequest 作用中時註冊之事件的來源 (您也可以將 CacheRequest 傳遞至 GetUpdatedCache 或其中一個 TreeWalker 方法，以此方式建立快取)。

  2. 使用 GetCachedPropertyValue，或從 AutomationElement 的 Cached 屬性擷取屬性。

取的快取的模式及其屬性

  1. 當 CacheRequest 在作用中時，使用 FindFirst 或 FindAll 取得 AutomationElement 物件；或取得 AutomationElement 做為 CacheRequest 作用中時註冊之事件的來源 (您也可以將 CacheRequest 傳遞至 GetUpdatedCache 或其中一個 TreeWalker 方法，以此方式建立快取)。

  2. 使用 GetCachedPattern 或 TryGetCachedPattern 擷取快取的模式。

  3. 從控制項模式的 Cached 屬性擷取屬性值。

範例

下列程式碼範例使用 Activate 啟動 CacheRequest，顯示快取的各個方面。

    ''' <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


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

下列程式碼範例使用 Push 啟動 CacheRequest，顯示快取的各個方面。 要將快取要求進行巢狀處理時則例外，這時最好使用 Activate。

''' <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

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

請參閱

概念

UI 自動化用戶端中的快取