Utiliser la mise en cache dans UI Automation
.gif "Remarque") Remarque |
|---|
Cette documentation s'adresse aux développeurs .NET Framework qui veulent utiliser les classes UI Automation managées définies dans l'espace de noms System.Windows.Automation.Pour obtenir les informations les plus récentes sur UI Automation, consultez API Windows Automation : UI Automation (page éventuellement en anglais). |
Cette section montre comment implémenter la mise en cache des propriétés AutomationElement et des modèles de contrôle.
Activer une requête de cache
Créez un CacheRequest.
Spécifiez les propriétés et les modèles à mettre en cache à l'aide de Add.
Spécifiez la portée de la mise en cache en définissant la propriété TreeScope.
Spécifiez l'affichage du sous-arbre en définissant la propriété TreeFilter.
Affectez à la propriété AutomationElementMode la valeur None si vous souhaitez augmenter l'efficacité en ne récupérant pas de référence complète aux objets. (Cela rendra impossible la récupération des valeurs actuelles de ces objets.)
Activez la requête en utilisant Activate dans un bloc using (Using dans Microsoft Visual Basic .NET).
Après l'obtention des objets AutomationElement ou l'abonnement à des événements, désactivez la requête en utilisant Pop (si Push a été utilisé) ou en supprimant l'objet créé par Activate. (Utilisez Activate dans un bloc using (Using dans Microsoft Visual Basic .NET).
Mettre en cache des propriétés AutomationElement
Lorsqu'un CacheRequest est actif, obtenez des objets AutomationElement en utilisant FindFirst ou FindAll, ou obtenez un AutomationElement comme source d'un événement pour lequel vous vous êtes inscrit lorsque le CacheRequest était actif. (Vous pouvez également créer un cache en passant un CacheRequest à GetUpdatedCache ou une des méthodes TreeWalker.)
Utilisez GetCachedPropertyValue ou récupérez une propriété de la propriété Cached du AutomationElement.
Obtenir des modèles mis en cache et leurs propriétés
Lorsqu'un CacheRequest est actif, obtenez des objets AutomationElement en utilisant FindFirst ou FindAll, ou obtenez un AutomationElement comme source d'un événement pour lequel vous vous êtes inscrit lorsque le CacheRequest était actif. (Vous pouvez également créer un cache en passant un CacheRequest à GetUpdatedCache ou une des méthodes TreeWalker.)
Utilisez GetCachedPattern ou TryGetCachedPattern pour récupérer un modèle mis en cache.
Récupérez des valeurs de propriété de la propriété Cached du modèle de contrôle.
Exemple
L'exemple de code suivant affiche différents aspects de la mise en cache, à l'aide de Activate pour activer 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;
}
L'exemple de code suivant affiche différents aspects de la mise en cache, à l'aide de Push pour activer CacheRequest. Excepté lorsque vous souhaitez imbriquer des requêtes de cache, il est préférable d'utiliser 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; ***/
}