CacheRequest Klasse

Definition

Gibt Eigenschaften und Muster an, die das „UI Automation“-Framework beim Abrufen eines AutomationElement zwischenspeichert.Specifies properties and patterns that the UI Automation framework caches when an AutomationElement is obtained.

public ref class CacheRequest sealed
public sealed class CacheRequest
type CacheRequest = class
Public NotInheritable Class CacheRequest
Vererbung
CacheRequest

Beispiele

Im folgenden Beispiel wird gezeigt, wie Activate zum Zwischenspeichern von Mustern und Eigenschaften verwendet wird.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;
}
''' <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

Im folgenden Beispiel wird gezeigt, wie Push und Pop verwendet werden, um Muster und Eigenschaften zwischenzuspeichern.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; ***/
}
''' <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

Hinweise

Zum Abrufen von Eigenschaften und Mustern BenutzeroberflächenautomatisierungUI Automation über sind prozessübergreifende Aufrufe erforderlich, die die Leistung beeinträchtigen können.Retrieving properties and patterns through BenutzeroberflächenautomatisierungUI Automation requires cross-process calls that can slow down performance. Durch das Zwischenspeichern von Werten von Eigenschaften und Mustern in einem Batch Vorgang können Sie die Leistung der Anwendung verbessern.By caching values of proprieties and patterns in a batch operation, you can enhance the performance of your application.

Erstellen Sie eine neue Cache Anforderung, indem Sie den-Klassenkonstruktor aufrufen.Create a new cache request by calling the class constructor. Die Anforderung wird durch wiederholte Aufrufe der Add -Methode aufgefüllt.The request is populated by repeated calls to the Add method.

Nur ein einzelner CacheRequest kann aktiv sein.Only a single CacheRequest can be active. Es gibt zwei Möglichkeiten, eine Anforderung zu aktivieren:There are two ways to activate a request:

  • Ruft Activate für die Anforderung auf.Call Activate on the request. Dadurch wird die Anforderung auf den Stapel übertragen, und die Anforderung wird per Pop ausgeblendet, wenn das Objekt verworfen wird.This pushes the request onto the stack, and the request is popped when the object is disposed. Um die Entfernung zu gewährleisten, auch wenn eine Ausnahme ausgelöst wird, verwenden Activate Sie den using RückgabewertUsing von innerhalb eines-Blocks (in Visual Basic).To ensure disposal even if an exception is raised, use the return value from Activate within a using block (Using in Visual Basic).

  • Fügen Sie die Anforderung auf den internen Stapel ein Push, indem Sie aufrufen.Put the request onto the internal stack by calling Push. Nur die oberste Anforderung auf dem Stapel ist aktiv, und Sie muss die nächste Anforderung sein, die aus dem Stapel Popentfernt wird.Only the topmost request on the stack is active, and it must be the next one removed from the stack by Pop. Durch das Pingen der Anforderung wird diese deaktiviert.Popping the request deactivates it.

BenutzeroberflächenautomatisierungUI AutomationElemente, die abgerufen werden, während die Anforderung aktiv ist, haben für die angegebenen Eigenschaften und Muster zwischengespeicherte Werte.elements obtained while the request is active will have cached values for the properties and patterns specified.

Konstruktoren

CacheRequest()

Initialisiert eine neue Instanz der CacheRequest-Klasse.Initializes a new instance of the CacheRequest class.

Eigenschaften

AutomationElementMode

Ruft einen Wert ab, der angibt, ob zurückgegebene Elemente vollständige Verweise auf die zugrunde liegende Benutzeroberfläche (User Interface, UI)user interface (UI) oder nur zwischengespeicherte Informationen enthalten sollen, oder legt diesen fest.Gets or sets a value that specifies whether returned elements should contain full references to the underlying Benutzeroberfläche (User Interface, UI)user interface (UI), or only cached information.

Current

Ruft den CacheRequest ab, der im aktuellen Thread aktiv ist.Gets the CacheRequest that is active on the current thread.

TreeFilter

Ruft einen Wert ab oder legt diesen fest, der die beim Zwischenspeichern zu verwendende Ansicht der BenutzeroberflächenautomatisierungUI Automation-Elementstruktur angibt.Gets or sets a value specifying the view of the BenutzeroberflächenautomatisierungUI Automation element tree to use when caching.

TreeScope

Ruft einen Wert ab, der angibt, ob das Zwischenspeichern nur für den Stamm der Teilstruktur oder auch für untergeordnete Elemente oder Nachfolgerelemente erfolgt, oder legt diesen fest.Gets or sets a value that specifies whether caching is done only for the root of the subtree, or also for its children or descendants.

Methoden

Activate()

Legt diesen CacheRequest als aktive Spezifikation für die Elemente fest, die zurückgegeben werden, wenn ein AutomationElement im gleichen Thread angefordert wird.Sets this CacheRequest as the active specification for the items that are returned when an AutomationElement is requested on the same thread.

Add(AutomationPattern)

Fügt den angegebenen AutomationPattern-Bezeichner diesem CacheRequest hinzu.Adds the specified AutomationPattern identifier to this CacheRequest.

Add(AutomationProperty)

Fügt den angegebenen AutomationProperty-Bezeichner diesem CacheRequest hinzu.Adds the specified AutomationProperty identifier to this CacheRequest.

Clone()

Erstellt eine Kopie dieser Instanz von CacheRequest.Creates a copy of this CacheRequest.

Equals(Object)

Ermittelt, ob das angegebene Objekt und das aktuelle Objekt gleich sind.Determines whether the specified object is equal to the current object.

(Geerbt von Object)
GetHashCode()

Dient als die Standard-HashfunktionServes as the default hash function.

(Geerbt von Object)
GetType()

Ruft den Type der aktuellen Instanz ab.Gets the Type of the current instance.

(Geerbt von Object)
MemberwiseClone()

Erstellt eine flache Kopie des aktuellen Object.Creates a shallow copy of the current Object.

(Geerbt von Object)
Pop()

Entfernt den aktiven CacheRequest aus dem internen Stapel für den aktuellen Thread.Removes the active CacheRequest from the internal stack for the current thread.

Push()

Platziert den CacheRequest auf dem internen Zustandsstapel, sodass diese die aktuelle Anforderung im aktuellen Thread wird.Places the CacheRequest on the internal state stack, making it the active request on the current thread.

ToString()

Gibt eine Zeichenfolge zurück, die das aktuelle Objekt darstellt.Returns a string that represents the current object.

(Geerbt von Object)

Gilt für:

Siehe auch