Automazione interfaccia utente di un controllo personalizzato WPFUI Automation of a WPF Custom Control

Automazione interfaccia utente MicrosoftMicrosoft UI Automation fornisce una singola interfaccia generalizzata che i client di automazione possono usare per esaminare o gestire le interfacce utente di una varietà di piattaforme e framework. provides a single, generalized interface that automation clients can use to examine or operate the user interfaces of a variety of platforms and frameworks. Automazione interfaccia utenteUI Automation consente sia al codice di controllo di qualità (test) sia alle applicazioni di accessibilità, ad esempio le utilità per la lettura dello schermo, di esaminare gli elementi dell'interfaccia utente e simulare l'interazione dell'utente da altro codice. enables both quality-assurance (test) code and accessibility applications such as screen readers to examine user-interface elements and simulate user interaction with them from other code. Per informazioni su Automazione interfaccia utenteUI Automation in tutte le piattaforme, vedere Accessibilità.For information about Automazione interfaccia utenteUI Automation across all platforms, see Accessibility.

L'articolo descrive come implementare un provider di automazione interfaccia utente sul lato server per un controllo personalizzato che viene eseguito in un'applicazione WPF.This topic describes how to implement a server-side UI Automation provider for a custom control that runs in a WPF application. WPF supporta Automazione interfaccia utenteUI Automation attraverso un albero di oggetti di automazione peer che affianca l'albero di elementi dell'interfaccia utente.WPF supports Automazione interfaccia utenteUI Automation through a tree of peer automation objects that parallels the tree of user interface elements. Il codice di test e le applicazioni che forniscono funzionalità di accessibilità possono usare gli oggetti peer di automazione direttamente (per il codice in-process) o tramite l'interfaccia generalizzata fornita da Automazione interfaccia utenteUI Automation.Test code and applications that provide accessibility features can use automation peer objects directly (for in-process code) or through the generalized interface provided by Automazione interfaccia utenteUI Automation.

Classi peer di automazioneAutomation Peer Classes

Supporto di controlli WPF Automazione interfaccia utenteUI Automation attraverso un albero delle classi peer che derivano da AutomationPeer.WPF controls support Automazione interfaccia utenteUI Automation through a tree of peer classes that derive from AutomationPeer. Per convenzione, i nomi delle classi peer iniziano con il nome della classe del controllo e terminano con "AutomationPeer".By convention, peer class names begin with the control class name and end with "AutomationPeer". Ad esempio, ButtonAutomationPeer è la classe peer per la Button classe del controllo.For example, ButtonAutomationPeer is the peer class for the Button control class. Le classi peer sono più o meno equivalenti ai tipi di controllo Automazione interfaccia utenteUI Automation, ma sono specifiche degli elementi WPFWPF.The peer classes are roughly equivalent to Automazione interfaccia utenteUI Automation control types but are specific to WPFWPF elements. Il codice di automazione che accede alle applicazioni WPF tramite l'interfaccia Automazione interfaccia utenteUI Automation non usa direttamente i peer di automazione, invece il codice di automazione nello stesso spazio di processo può usarli direttamente.Automation code that accesses WPF applications through the Automazione interfaccia utenteUI Automation interface does not use automation peers directly, but automation code in the same process space can use automation peers directly.

Classi peer di automazione integrateBuilt-in Automation Peer Classes

Gli elementi implementano una classe peer di automazione se accettano l'attività dell'interfaccia da parte dell'utente o se contengono le informazioni necessarie per gli utenti di applicazioni per la lettura dello schermo.Elements implement an automation peer class if they accept interface activity from the user, or if they contain information needed by users of screen-reader applications. Non tutti gli oggetti visivi WPF dispongono di peer di automazione.Not all WPF visual elements have automation peers. Esempi di classi che implementano peer di automazione sono Button, TextBox, e Label.Examples of classes that implement automation peers are Button, TextBox, and Label. Esempi di classi che implementano i peer di automazione sono classi che derivano da Decorator, ad esempio Bordere le classi basate su Panel, ad esempio Grid e Canvas.Examples of classes that do not implement automation peers are classes that derive from Decorator, such as Border, and classes based on Panel, such as Grid and Canvas.

La base Control classe dispone di una classe peer corrispondente.The base Control class does not have a corresponding peer class. Se è necessaria una classe di peer in modo che corrisponda a un controllo personalizzato deriva da Control, è necessario derivare la classe peer personalizzata da FrameworkElementAutomationPeer.If you need a peer class to correspond to a custom control that derives from Control, you should derive the custom peer class from FrameworkElementAutomationPeer.

Considerazioni sulla sicurezza per i peer derivatiSecurity Considerations for Derived Peers

I peer di automazione devono essere eseguiti in un ambiente parzialmente attendibile.Automation peers must run in a partial-trust environment. Il codice nell'assembly UIAutomationClient non è configurato per l'esecuzione in un ambiente parzialmente attendibile e il codice di peer di automazione non deve fare riferimento a tale assembly.Code in the UIAutomationClient assembly is not configured to run in a partial-trust environment, and automation peer code should not reference that assembly. È consigliabile invece usare le classi nell'assembly UIAutomationTypes.Instead, you should use the classes in the UIAutomationTypes assembly. Ad esempio, è necessario utilizzare il AutomationElementIdentifiers classe dell'assembly UIAutomationTypes, che corrisponde alla AutomationElement classe nell'assembly UIAutomationClient.For example, you should use the AutomationElementIdentifiers class from the UIAutomationTypes assembly, which corresponds to the AutomationElement class in the UIAutomationClient assembly. Un modo sicuro consiste nel fare riferimento all'assembly UIAutomationTypes nel codice del peer di automazione.It is safe to reference the UIAutomationTypes assembly in automation peer code.

Navigazione nel peerPeer Navigation

Dopo aver individuato un peer di automazione, il codice in-process può esplorare l'albero di peer, chiamare l'oggetto GetChildren e GetParent metodi.After locating an automation peer, in-process code can navigate the peer tree by calling the object's GetChildren and GetParent methods. Spostamento tra WPFWPF elementi all'interno di un controllo è supportato dall'implementazione del peer la GetChildrenCore metodo.Navigation among WPFWPF elements within a control is supported by the peer's implementation of the GetChildrenCore method. Il sistema di Automazione interfaccia utente chiama questo metodo per creare un albero di sottoelementi contenuti in un controllo, come ad esempio le voci di una casella di riepilogo.The UI Automation system calls this method to build up a tree of subelements contained within a control; for example, list items in a list box. Il valore predefinito UIElementAutomationPeer.GetChildrenCore metodo attraversa la struttura ad albero visuale degli elementi per creare la struttura dei peer di automazione.The default UIElementAutomationPeer.GetChildrenCore method traverses the visual tree of elements to build the tree of automation peers. I controlli personalizzati eseguono l'override del metodo per esporre gli elementi figlio ai client di automazione, restituendo i peer di automazione di elementi che contengono informazioni o consentono l'interazione da parte dell'utente.Custom controls override this method to expose children elements to automation clients, returning the automation peers of elements that convey information or allow user interaction.

Personalizzazioni in un peer derivatoCustomizations in a Derived Peer

Tutte le classi che derivano da UIElement e ContentElement contengono il metodo virtuale protetto OnCreateAutomationPeer.All classes that derive from UIElement and ContentElement contain the protected virtual method OnCreateAutomationPeer. WPF chiama OnCreateAutomationPeer per ottenere l'oggetto di peer di automazione per ogni controllo.WPF calls OnCreateAutomationPeer to get the automation peer object for each control. Il codice di automazione può usare il peer per ottenere informazioni sulle funzionalità e le caratteristiche di un controllo e per simulare l'uso interattivo.Automation code can use the peer to get information about a control’s characteristics and features and to simulate interactive use. È necessario eseguire l'override di un controllo personalizzato che supporta l'automazione OnCreateAutomationPeer e restituire un'istanza di una classe che deriva da AutomationPeer.A custom control that supports automation must override OnCreateAutomationPeer and return an instance of a class that derives from AutomationPeer. Ad esempio, se un controllo personalizzato deriva dal ButtonBase classe, quindi l'oggetto restituito da OnCreateAutomationPeer deve derivare da ButtonBaseAutomationPeer.For example, if a custom control derives from the ButtonBase class, then the object returned by OnCreateAutomationPeer should derive from ButtonBaseAutomationPeer.

Quando si implementa un controllo personalizzato, è necessario eseguire l'override dei metodi "Core" dalla classe peer di automazione di base che descrivono il comportamento univoco e specifico del controllo personalizzato.When implementing a custom control, you must override the "Core" methods from the base automation peer class that describe behavior unique and specific to your custom control.

Override di OnCreateAutomationPeerOverride OnCreateAutomationPeer

Eseguire l'override di OnCreateAutomationPeer metodo per il controllo personalizzato in modo che restituisca l'oggetto provider deve derivare direttamente o indirettamente da AutomationPeer.Override the OnCreateAutomationPeer method for your custom control so that it returns your provider object, which must derive directly or indirectly from AutomationPeer.

Override di GetPatternOverride GetPattern

I peer di automazione semplificano alcuni aspetti dell'implementazione di provider Automazione interfaccia utenteUI Automation sul lato server, tuttavia i peer di automazione di controlli personalizzati devono comunque gestire le interfacce dei criteri.Automation peers simplify some implementation aspects of server-side Automazione interfaccia utenteUI Automation providers, but custom control automation peers must still handle pattern interfaces. Ad esempio il provider non WPF, peer supportano i pattern di controllo fornendo implementazioni delle interfacce nel System.Windows.Automation.Provider dello spazio dei nomi, ad esempio IInvokeProvider.Like non-WPF providers, peers support control patterns by providing implementations of interfaces in the System.Windows.Automation.Provider namespace, such as IInvokeProvider. Le interfacce dei criteri di controllo possono essere implementate dal peer stesso o da un altro oggetto.The control pattern interfaces can be implemented by the peer itself or by another object. Implementazione del peer GetPattern restituisce l'oggetto che supporta il pattern specificato.The peer's implementation of GetPattern returns the object that supports the specified pattern. Automazione interfaccia utenteUI Automation codice chiama il GetPattern (metodo) e specifica un PatternInterface valore di enumerazione. code calls the GetPattern method and specifies a PatternInterface enumeration value. L'override del GetPattern deve restituire l'oggetto che implementa il pattern specificato.Your override of GetPattern should return the object that implements the specified pattern. Se il controllo non ha un'implementazione personalizzata di un modello, è possibile chiamare l'implementazione del tipo di base di GetPattern per recuperare la relativa implementazione o null se il pattern non è supportato per questo tipo di controllo.If your control does not have a custom implementation of a pattern, you can call the base type's implementation of GetPattern to retrieve either its implementation or null if the pattern is not supported for this control type. Ad esempio, è possibile impostare un controllo personalizzato NumericUpDown su un valore all'interno di un intervallo, in modo relativo Automazione interfaccia utenteUI Automation peer implementi il IRangeValueProvider interfaccia.For example, a custom NumericUpDown control can be set to a value within a range, so its Automazione interfaccia utenteUI Automation peer would implement the IRangeValueProvider interface. L'esempio seguente viene illustrato come il peer GetPattern viene eseguito l'override di metodo per rispondere a un PatternInterface.RangeValue valore.The following example shows how the peer's GetPattern method is overridden to respond to a PatternInterface.RangeValue value.

public override object GetPattern(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.RangeValue)
    {
        return this;
    }
    return base.GetPattern(patternInterface);
}
Public Overrides Function GetPattern(ByVal patternInterface As PatternInterface) As Object
	If patternInterface = PatternInterface.RangeValue Then
		Return Me
	End If
	Return MyBase.GetPattern(patternInterface)
End Function

Oggetto GetPattern metodo è possibile specificare anche un sottoelemento come provider di pattern.A GetPattern method can also specify a subelement as a pattern provider. Il codice seguente viene illustrato come ItemsControl i trasferimenti di scorrere la gestione del pattern per il peer di interni ScrollViewer controllo.The following code shows how ItemsControl transfers scroll pattern handling to the peer of its internal ScrollViewer control.

public override object GetPattern(PatternInterface patternInterface)  
{  
    if (patternInterface == PatternInterface.Scroll)  
    {  
        ItemsControl owner = (ItemsControl) base.Owner;  

        // ScrollHost is internal to the ItemsControl class  
        if (owner.ScrollHost != null)  
        {  
            AutomationPeer peer = UIElementAutomationPeer.CreatePeerForElement(owner.ScrollHost);  
            if ((peer != null) && (peer is IScrollProvider))  
            {  
                peer.EventsSource = this;  
                return (IScrollProvider) peer;  
            }  
        }  
    }  
    return base.GetPattern(patternInterface);  
}  
Public Class Class1  
    Public Overrides Function GetPattern(ByVal patternInterface__1 As PatternInterface) As Object  
        If patternInterface1 = PatternInterface.Scroll Then  
            Dim owner As ItemsControl = DirectCast(MyBase.Owner, ItemsControl)  

            ' ScrollHost is internal to the ItemsControl class  
            If owner.ScrollHost IsNot Nothing Then  
                Dim peer As AutomationPeer = UIElementAutomationPeer.CreatePeerForElement(owner.ScrollHost)  
                If (peer IsNot Nothing) AndAlso (TypeOf peer Is IScrollProvider) Then  
                    peer.EventsSource = Me  
                    Return DirectCast(peer, IScrollProvider)  
                End If  
            End If  
        End If  
        Return MyBase.GetPattern(patternInterface1)  
    End Function  
End Class  

Per specificare un sottoelemento per la gestione del pattern, questo codice ottiene l'oggetto del sottoelemento, crea un peer tramite il CreatePeerForElement metodo, imposta la EventsSource proprietà del nuovo peer peer corrente e restituisce il nuovo peer.To specify a subelement for pattern handling, this code gets the subelement object, creates a peer by using the CreatePeerForElement method, sets the EventsSource property of the new peer to the current peer, and returns the new peer. Impostazione EventsSource su un sottoelemento impedisce il sottoelemento nell'albero di peer di automazione e definisce tutti gli eventi generati dal sottoelemento come proveniente dal controllo specificato EventsSource.Setting EventsSource on a subelement prevents the subelement from appearing in the automation peer tree and designates all events raised by the subelement as originating from the control specified in EventsSource. Il ScrollViewer controllo non viene visualizzato nell'albero di automazione e risultano provenienti da eventi di scorrimento che genera il ItemsControl oggetto.The ScrollViewer control does not appear in the automation tree, and scrolling events that it generates appear to originate from the ItemsControl object.

Override dei metodi "Core"Override "Core" Methods

Il codice di automazione ottiene informazioni sul controllo tramite chiamate a metodi pubblici della classe peer.Automation code gets information about your control by calling public methods of the peer class. Per fornire informazioni sul controllo, eseguire l'override di ogni metodo il cui nome termina con "Core" quando l'implementazione del controllo differisce da quella fornita dalla classe peer di automazione di base.To provide information about your control, override each method whose name ends with "Core" when your control implementation differs from that of that provided by the base automation peer class. Come minimo, il controllo deve implementare il GetClassNameCore e GetAutomationControlTypeCore metodi, come illustrato nell'esempio seguente.At a minimum, your control must implement the GetClassNameCore and GetAutomationControlTypeCore methods, as shown in the following example.

protected override string GetClassNameCore()
{
    return "NumericUpDown";
}

protected override AutomationControlType GetAutomationControlTypeCore()
{
    return AutomationControlType.Spinner;
}
Protected Overrides Function GetClassNameCore() As String
	Return "NumericUpDown"
End Function

Protected Overrides Function GetAutomationControlTypeCore() As AutomationControlType
	Return AutomationControlType.Spinner
End Function

L'implementazione di GetAutomationControlTypeCore descrive il controllo tramite la restituzione di un ControlType valore.Your implementation of GetAutomationControlTypeCore describes your control by returning a ControlType value. Sebbene sia possibile restituire ControlType.Custom, è necessario restituire uno dei tipi di controllo più specifici se il controllo viene descritto in modo accurato.Although you can return ControlType.Custom, you should return one of the more specific control types if it accurately describes your control. Valore restituito di ControlType.Custom richiede inoltre lavoro aggiuntivo per il provider implementare Automazione interfaccia utenteUI Automation, e Automazione interfaccia utenteUI Automation prodotti client sono in grado di prevedere la struttura di controllo, l'interazione di tastiera e pattern di controllo possibili.A return value of ControlType.Custom requires extra work for the provider to implement Automazione interfaccia utenteUI Automation, and Automazione interfaccia utenteUI Automation client products are unable to anticipate the control structure, keyboard interaction, and possible control patterns.

Implementare il IsContentElementCore e IsControlElementCore metodi per indicare se il controllo contiene il contenuto dei dati o svolge un ruolo interattivo nell'interfaccia utente (o entrambe).Implement the IsContentElementCore and IsControlElementCore methods to indicate whether your control contains data content or fulfills an interactive role in the user interface (or both). Per impostazione predefinita, entrambi i metodi restituiscono true.By default, both methods return true. Queste impostazioni migliorano l'usabilità di strumenti di automazione, come le utilità per la lettura dello schermo, i quali possono usare questi metodi per filtrare l'albero di automazione.These settings improve the usability of automation tools such as screen readers, which may use these methods to filter the automation tree. Se il GetPattern metodo trasferimenti modello gestione a un sottoelemento, il peer del sottoelemento del peer IsControlElementCore metodo può restituire false per nascondere il peer del sottoelemento dall'albero di automazione.If your GetPattern method transfers pattern handling to a subelement peer, the subelement peer's IsControlElementCore method can return false to hide the subelement peer from the automation tree. Ad esempio, lo scorrimento in un ListBox viene gestita da un ScrollViewere il peer di automazione per PatternInterface.Scroll restituito dal GetPattern metodo del ScrollViewerAutomationPeer associato il ListBoxAutomationPeer. Pertanto, il IsControlElementCore metodo il ScrollViewerAutomationPeer restituisce false, in modo che il ScrollViewerAutomationPeer non viene visualizzato nell'albero di automazione.For example, scrolling in a ListBox is handled by a ScrollViewer, and the automation peer for PatternInterface.Scroll is returned by the GetPattern method of the ScrollViewerAutomationPeer that is associated with the ListBoxAutomationPeer.Therefore, the IsControlElementCore method of the ScrollViewerAutomationPeer returns false, so that the ScrollViewerAutomationPeer does not appear in the automation tree.

Il peer di automazione deve fornire valori predefiniti appropriati per il controllo.Your automation peer should provide appropriate default values for your control. Si noti che il codice XAML che fa riferimento al controllo può eseguire l'override delle implementazioni peer dei metodi di base includendo AutomationProperties attributi.Note that XAML that references your control can override your peer implementations of core methods by including AutomationProperties attributes. Il codice XAML seguente, ad esempio, crea un pulsante che dispone di due proprietà Automazione interfaccia utenteUI Automation personalizzate.For example, the following XAML creates a button that has two customized Automazione interfaccia utenteUI Automation properties.

<Button AutomationProperties.Name="Special"   
    AutomationProperties.HelpText="This is a special button."/>  

Implementare i provider di criteriImplement Pattern Providers

Le interfacce implementate da un provider personalizzato sono dichiarate in modo esplicito se l'elemento proprietario deriva direttamente da Control.The interfaces implemented by a custom provider are explicitly declared if the owning element derives directly from Control. Ad esempio, il codice seguente viene dichiarato un peer per un Control che implementa un intervallo di valori.For example, the following code declares a peer for a Control that implements a range value.

public class RangePeer1 : FrameworkElementAutomationPeer, IRangeValueProvider { }  
Public Class RangePeer1  
    Inherits FrameworkElementAutomationPeer  
    Implements IRangeValueProvider  
End Class  

Se il controllo proprietario deriva da un tipo specifico di controllo, ad esempio RangeBase, il peer può essere derivato da una classe peer derivata equivalente.If the owning control derives from a specific type of control such as RangeBase, the peer can be derived from an equivalent derived peer class. In questo caso, il peer deriva da RangeBaseAutomationPeer, che fornisce un'implementazione di base di IRangeValueProvider.In this case, the peer would derive from RangeBaseAutomationPeer, which supplies a base implementation of IRangeValueProvider. Il codice seguente mostra la dichiarazione di un peer di questo tipo.The following code shows the declaration of such a peer.

public class RangePeer2 : RangeBaseAutomationPeer { }  
Public Class RangePeer2  
    Inherits RangeBaseAutomationPeer  
End Class  

Per un esempio di implementazione, vedere Esempio di controllo personalizzato NumericUpDown con supporto di tema e automazione interfaccia utente.For an example implementation, see NumericUpDown Custom Control with Theme and UI Automation Support Sample.

Generare eventiRaise Events

I client di automazione possono sottoscrivere eventi di automazione.Automation clients can subscribe to automation events. Controlli personalizzati devono segnalare le modifiche allo stato del controllo chiamando la RaiseAutomationEvent metodo.Custom controls must report changes to control state by calling the RaiseAutomationEvent method. Analogamente, quando un valore della proprietà viene modificato, chiamare il RaisePropertyChangedEvent metodo.Similarly, when a property value changes, call the RaisePropertyChangedEvent method. Il codice seguente mostra come ottenere l'oggetto peer dall'interno del codice del controllo e chiamare un metodo per generare un evento.The following code shows how to get the peer object from within the control code and call a method to raise an event. Per ottimizzare la procedura, il codice determina se sono presenti listener per questo tipo di evento.As an optimization, the code determines if there are any listeners for this event type. La generazione dell'evento solo in presenza di listener evita un sovraccarico inutile e consente al controllo di rimane pronto a rispondere.Raising the event only when there are listeners avoids unnecessary overhead and helps the control remain responsive.

if (AutomationPeer.ListenerExists(AutomationEvents.PropertyChanged))
{
    NumericUpDownAutomationPeer peer = 
        UIElementAutomationPeer.FromElement(nudCtrl) as NumericUpDownAutomationPeer;

    if (peer != null)
    {
        peer.RaisePropertyChangedEvent(
            RangeValuePatternIdentifiers.ValueProperty,
            (double)oldValue,
            (double)newValue);
    }
}
If AutomationPeer.ListenerExists(AutomationEvents.PropertyChanged) Then
	Dim peer As NumericUpDownAutomationPeer = TryCast(UIElementAutomationPeer.FromElement(nudCtrl), NumericUpDownAutomationPeer)

	If peer IsNot Nothing Then
		peer.RaisePropertyChangedEvent(RangeValuePatternIdentifiers.ValueProperty, CDbl(oldValue), CDbl(newValue))
	End If
End If

Vedere ancheSee Also

Panoramica di automazione interfaccia utenteUI Automation Overview
Controllo personalizzato NumericUpDown con esempio supporto di automazione interfaccia utente e del temaNumericUpDown Custom Control with Theme and UI Automation Support Sample
Implementazione del provider di automazione interfaccia utente lato serverServer-Side UI Automation Provider Implementation