Implementazione del provider di automazione interfaccia utente lato server

Articolo
08/11/2011

Nota
La presente documentazione è destinata agli sviluppatori di .NET Framework che desiderano utilizzare le classi UI Automation gestite definite nello spazio dei nomi System.Windows.Automation.Per informazioni aggiornate sull'UI Automation, vedere Windows Automation API: Automazione interfaccia utente (la pagina potrebbe essere in inglese).

In questa sezione viene descritto come implementare un provider di automazione interfaccia utente lato server per un controllo personalizzato.

L'implementazione per gli elementi Windows Presentation Foundation (WPF) è fondamentalmente diversa da quella per gli elementi non WPF, ad esempio quelli progettati per Windows Forms. Gli elementi WPF forniscono supporto per l'UI Automation tramite una classe derivata da AutomationPeer. Gli elementi non WPF forniscono supporto tramite implementazioni di interfacce di provider.

Nel presente argomento sono contenute le seguenti sezioni.

Considerazioni sulla sicurezza
Implementazione del provider tramite elementi Windows Presentation Foundation
Implementazione del provider tramite elementi non WPF
Argomenti correlati

Considerazioni sulla sicurezza

I provider devono essere scritti in modo che possano funzionare in un ambiente parzialmente attendibile. Poiché UIAutomationClient.dll non è configurato per l'esecuzione in attendibilità parziale, il codice del provider non deve fare riferimento a questo assembly. In caso contrario, il codice potrebbe essere eseguito in un ambiente completamente attendibile ma poi generare errori in un ambiente parzialmente attendibile.

In particolare, non utilizzare i campi delle classi di UIAutomationClient.dll, ad esempio quelli in AutomationElement. Utilizzare invece i campi equivalenti delle classi di UIAutomationTypes.dll, ad esempio AutomationElementIdentifiers.

Implementazione del provider tramite elementi Windows Presentation Foundation

Per ulteriori informazioni su questo argomento, vedere UI Automation of a WPF Custom Control.

Implementazione del provider tramite elementi non WPF

I controlli personalizzati che non fanno parte del framework WPF, ma che sono scritti in codice gestito (il più delle volte si tratta di controlli Windows Forms), forniscono supporto per UI Automation tramite l'implementazione di interfacce. Ogni elemento deve implementare almeno una delle interfacce elencate nella prima tabella della sezione successiva. Inoltre, se l'elemento supporta uno o più pattern di controllo, deve implementare l'interfaccia appropriata per ognuno di essi.

Il progetto del provider di UI Automation deve fare riferimento agli assembly seguenti:

UIAutomationProviders.dll
UIAutomationTypes.dll
WindowsBase.dll

Nella presente sezione sono contenute le seguenti sottosezioni.

Interfacce di provider
Requisiti per i provider non WPF
Valori delle proprietà nei provider non WPF
Eventi nei provider non WPF
Spostamento per i provider non WPF
Assegnazione di nuovi elementi padre per i provider non WPF
Riposizionamento per i provider non WPF

Interfacce di provider

Ogni provider di UI Automation deve implementare una delle interfacce seguenti.

Interfaccia	Descrizione
IRawElementProviderSimple	Fornisce la funzionalità per un controllo semplice contenuto in una finestra, incluso il supporto per pattern di controllo e proprietà.
IRawElementProviderFragment	Eredita da IRawElementProviderSimple. Aggiunge la funzionalità per un elemento in un controllo complesso, inclusi lo spostamento all'interno del frammento, l'impostazione dello stato attivo e la restituzione del rettangolo di delimitazione dell'elemento.
IRawElementProviderFragmentRoot	Eredita da IRawElementProviderFragment. Aggiunge la funzionalità per l'elemento radice in un controllo complesso, inclusi il posizionamento di un elemento figlio in corrispondenza di coordinate specificate e l'impostazione dello stato attivo per l'intero controllo.

Le interfacce seguenti forniscono funzionalità aggiuntive ma non è obbligatorio implementarle.

Interfaccia	Descrizione
IRawElementProviderAdviseEvents	Consente al provider di tenere traccia delle richieste di eventi.
IRawElementProviderHwndOverride	Abilita il riposizionamento di elementi basati su finestre all'interno della struttura ad albero di UI Automation di un frammento.

Tutte le altre interfacce nello spazio dei nomi System.Windows.Automation.Provider sono per il supporto di pattern di controllo.

Requisiti per i provider non WPF

Per comunicare con UI Automation, il controllo deve implementare le principali aree di funzionalità seguenti:

Funzionalità	Implementazione
Esporre il provider a UI Automation	In risposta ad un messaggio WM_GETOBJECT inviato alla finestra del controllo, restituire l'oggetto che implementa IRawElementProviderSimple o un'interfaccia derivata. Per i frammenti, deve trattarsi del provider per la radice del frammento.
Fornire i valori delle proprietà	Implementare GetPropertyValue per fornire o eseguire l'override di valori.
Abilitare il client per l'interazione con il controllo	Implementare interfacce che supportano pattern di controllo, ad esempio IInvokeProvider. Restituire questi provider di pattern nell'implementazione di GetPatternProvider.
Generare eventi	Chiamare uno dei metodi statici di AutomationInteropProvider per generare un evento di cui un client può rimanere in ascolto.
Abilitare lo spostamento e l'impostazione dello stato attivo all'interno di un frammento	Implementare IRawElementProviderFragment per ogni elemento all'interno del frammento. Questa operazione non è necessaria per gli elementi che non fanno parte di un frammento.
Abilitare l'impostazione dello stato attivo e il posizionamento di un elemento figlio in un frammento	Implementare IRawElementProviderFragmentRoot Questa operazione non è necessaria per gli elementi che non sono radici di frammenti.

Valori delle proprietà nei provider non WPF

I provider di UI Automation per i controlli personalizzati devono supportare determinate proprietà che possono essere utilizzate dal sistema di automazione così come dalle applicazioni client. Per gli elementi contenuti nelle finestre (HWND), UI Automation può recuperare alcune proprietà dal provider di finestre predefinito, ma deve ottenere le altre dal provider personalizzato.

In genere, i provider per i controlli basati su HWND non devono necessariamente fornire le proprietà seguenti (identificate da valori di campo):

Nota
Il campo RuntimeIdProperty di un elemento semplice o di una radice di frammento contenuta in una finestra si ottiene dalla finestra. Tuttavia, gli elementi del frammento al di sotto della radice (ad esempio gli elementi di un elenco in una casella di riepilogo) devono fornire i propri identificatori.Per ulteriori informazioni, vedere GetRuntimeId. Il campo IsKeyboardFocusableProperty deve essere restituito per i provider contenuti in un controllo Windows Forms.In questo caso, il provider di finestre predefinito può non essere in grado di recuperare il valore corretto. Il campo NameProperty viene in genere fornito dal provider host.Ad esempio, se un controllo personalizzato è derivato da Control, il nome è derivato dalla proprietà Text del controllo.

Il campo RuntimeIdProperty di un elemento semplice o di una radice di frammento contenuta in una finestra si ottiene dalla finestra. Tuttavia, gli elementi del frammento al di sotto della radice (ad esempio gli elementi di un elenco in una casella di riepilogo) devono fornire i propri identificatori.Per ulteriori informazioni, vedere GetRuntimeId.

Il campo IsKeyboardFocusableProperty deve essere restituito per i provider contenuti in un controllo Windows Forms.In questo caso, il provider di finestre predefinito può non essere in grado di recuperare il valore corretto.

Il campo NameProperty viene in genere fornito dal provider host.Ad esempio, se un controllo personalizzato è derivato da Control, il nome è derivato dalla proprietà Text del controllo.

Per visualizzare il codice di esempio, vedere Restituire proprietà da un provider di automazione interfaccia utente.

Eventi nei provider non WPF

I provider di UI Automation devono generare eventi per notificare alle applicazioni client le modifiche nello stato dell'interfaccia utente. Per generare eventi, vengono utilizzati i metodi seguenti.

Metodo	Descrizione
RaiseAutomationEvent	Genera vari eventi, inclusi quelli attivati dai pattern di controllo.
RaiseAutomationPropertyChangedEvent	Genera un evento quando una proprietà di UI Automation è stata modificata.
RaiseStructureChangedEvent	Genera un evento quando la struttura ad albero di UI Automation è stata modificata, ad esempio con la rimozione o l'aggiunta di un elemento.

Lo scopo di un evento è notificare al client qualcosa che si verifica nell'user interface (UI), sia che l'attività venga attivata o meno dal sistema di UI Automation. Ad esempio, l'evento identificato da InvokedEvent deve essere generato ogni volta che il controllo viene richiamato, tramite input diretto dell'utente o dall'applicazione client che effettua una chiamata a Invoke.

Per ottimizzare le prestazioni, un provider può generare eventi in modo selettivo oppure non generarne affatto se nessuna applicazione client si è registrata per riceverli. Per l'ottimizzazione, vengono utilizzati i metodi seguenti.

Metodo	Descrizione
ClientsAreListening	Questa proprietà statica specifica se alcune applicazioni client hanno sottoscritto gli eventi di UI Automation.
IRawElementProviderAdviseEvents	Con l'implementazione del provider di questa interfaccia su una radice di frammento, l'interfaccia riceve una notifica quando i client registrano e annullano la registrazione dei gestori eventi per gli eventi sul frammento.

Spostamento per i provider non WPF

I provider per controlli semplici come ad esempio un pulsante personalizzato contenuto in una finestra (HWND) non devono necessariamente supportare lo spostamento all'interno della struttura ad albero di UI Automation. Lo spostamento da e verso l'elemento viene gestito dal provider predefinito per la finestra host, specificato nell'implementazione di HostRawElementProvider. Quando si implementa un provider per un controllo personalizzato complesso, tuttavia, è necessario supportare lo spostamento tra il nodo radice del frammento e i relativi discendenti, nonché tra nodi di pari livello.

Nota
Gli elementi di un frammento diversi dalla radice devono restituire un riferimento null da HostRawElementProvider, perché non sono contenuti direttamente in una finestra e nessun provider predefinito può supportare lo spostamento verso e da tali elementi.

La struttura del frammento è determinata dall'implementazione di Navigate. Per ogni possibile direzione da ogni frammento, questo metodo restituisce l'oggetto provider per l'elemento in quella direzione. Se in questa direzione non esistono elementi, il metodo restituisce un riferimento null.

La radice del frammento supporta lo spostamento solo verso gli elementi figlio. Ad esempio, una casella di riepilogo restituisce il primo elemento nell'elenco quando la direzione è FirstChild e l'ultimo elemento quando la direzione è LastChild. La radice del frammento non supporta lo spostamento verso un elemento padre o di pari livello. Questa operazione è gestita dal provider della finestra host.

Gli elementi di un frammento diversi dalla radice devono supportare lo spostamento verso l'elemento padre, nonché verso i propri elementi di pari livello o figlio, se disponibili.

Assegnazione di nuovi elementi padre per i provider non WPF

Le finestre popup sono in realtà finestre di primo livello, quindi per impostazione predefinita vengono visualizzate nella struttura ad albero di UI Automation come elementi figlio del desktop. In molti casi, tuttavia, le finestre popup sono logicamente elementi figlio di un altro controllo. Ad esempio, l'elenco a discesa di una casella combinata è logicamente un elemento figlio della casella combinata. Analogamente, una finestra popup di un menu è logicamente un elemento figlio del menu. In UI Automation è possibile assegnare un nuovo elemento padre alle finestre popup in modo che vengano visualizzate come elementi figlio del controllo associato.

Per assegnare un nuovo elemento padre a una finestra popup:

Creare un provider per la finestra popup. Per eseguire questa operazione, è necessario conoscere in anticipo la classe della finestra popup.
Implementare come al solito tutte le proprietà e i pattern per tale popup, come se si trattasse di un controllo autonomo.
Implementare la proprietà HostRawElementProvider in modo che restituisca il valore ottenuto da HostProviderFromHandle, dove il parametro è l'handle di finestra della finestra popup.
Implementare Navigate per la finestra popup e il relativo elemento padre in modo che lo spostamento venga gestito correttamente dall'elemento padre logico agli elementi figlio logici e tra gli elementi figlio di pari livello.

Quando UI Automation rileva la finestra popup, riconosce che è stato eseguito l'override dello spostamento predefinito e ignora la finestra popup quando viene rilevata come elemento figlio del desktop. Il nodo sarà raggiungibile solo tramite il frammento.

L'assegnazione di un nuovo elemento padre non è indicata nei casi in cui un controllo possa contenere una finestra di qualsiasi classe. Ad esempio un controllo Rebar può contenere qualsiasi tipo di HWND nelle proprie bande. Per gestire questi casi, UI Automation supporta un tipo alternativo di rilocazione HWND, come descritto nella sezione seguente.

Riposizionamento per i provider non WPF

I frammenti di UI Automation possono contenere due o più elementi, ognuno contenuto in una finestra (HWND). Poiché ogni elemento HWND ha il proprio provider predefinito che lo considera un elemento figlio di un HWND che lo contiene, per impostazione predefinita la struttura ad albero di UI Automation visualizzerà gli HWND nel frammento come elementi figlio della finestra padre. Nella maggior parte dei casi questo comportamento è utile, ma talvolta può generare confusione perché non corrisponde alla struttura logica della UI.

Un esempio efficace è un controllo Rebar. Un Rebar contiene bande, ognuna delle quali può a sua volta contenere un controllo basato su HWND, ad esempio una barra degli strumenti, una casella di modifica o una casella combinata. Il provider di finestre predefinito per l'HWND del Rebar riconosce gli HWND del controllo come elementi figlio e il provider del Rebar riconosce le bande come elementi figlio. Poiché il provider HWND e il provider del Rebar agiscono insieme e combinano i propri elementi figlio, le bande e i controlli basati su HWND vengono visualizzati come elementi figlio del Rebar. A livello logico, tuttavia, solo le bande devono apparire come elementi figlio del Rebar e ogni provider di bande deve essere abbinato al provider HWND predefinito per il controllo che contiene.

Per ottenere questo risultato, il provider della radice del frammento per il Rebar espone un insieme di elementi figlio che rappresentano le bande. Ogni banda ha un singolo provider che può esporre proprietà e pattern. Nella propria implementazione di HostRawElementProvider, il provider di bande restituisce il provider di finestre predefinito per l'HWND del controllo, che ottiene tramite una chiamata a HostProviderFromHandle, passando l'handle della finestra del controllo. Infine, il provider della radice del frammento per il Rebar implementa l'interfaccia IRawElementProviderHwndOverride e nell'implementazione di GetOverrideProviderForHwnd restituisce il provider di bande appropriato per il controllo contenuto nell'HWND specificato.