Delen via

Implementatie van ui-automatiseringsprovider aan de serverzijde

  • Artikel

Notitie

Deze documentatie is bedoeld voor .NET Framework-ontwikkelaars die de beheerde UI Automation-klassen willen gebruiken die zijn gedefinieerd in de System.Windows.Automation naamruimte. Zie Windows Automation-API: UI Automation voor de meest recente informatie over UI Automation.

In deze sectie wordt beschreven hoe u een UI Automation-provider aan de serverzijde implementeert voor een aangepast besturingselement.

De implementatie voor WPF-elementen (Windows Presentation Foundation) en niet-WPF-elementen (zoals de elementen die zijn ontworpen voor Windows Forms) is fundamenteel anders. WPF-elementen bieden ondersteuning voor UI Automation via een klasse die is afgeleid van AutomationPeer. Niet-WPF-elementen bieden ondersteuning via implementaties van providerinterfaces.

Beveiligingsoverwegingen

Providers moeten worden geschreven zodat ze in een gedeeltelijke vertrouwensomgeving kunnen werken. Omdat UIAutomationClient.dll niet is geconfigureerd om te worden uitgevoerd onder gedeeltelijke vertrouwensrelatie, mag uw providercode niet verwijzen naar die assembly. Als dit het geval is, kan de code worden uitgevoerd in een omgeving met volledige vertrouwensrelatie, maar vervolgens mislukken in een gedeeltelijke vertrouwensomgeving.

Gebruik met name geen velden uit klassen in UIAutomationClient.dll zoals die in AutomationElement. Gebruik in plaats daarvan de equivalente velden uit klassen in UIAutomationTypes.dll, zoals AutomationElementIdentifiers.

Implementatie van providers door Windows Presentation Foundation-elementen

Zie UI-automatisering van een aangepast WPF-besturingselement voor meer informatie over dit onderwerp.

Provider-implementatie door niet-WPF-elementen

Aangepaste besturingselementen die geen deel uitmaken van het WPF-framework, maar die zijn geschreven in beheerde code (meestal dit zijn Besturingselementen voor Windows Forms), bieden ondersteuning voor UI Automation door interfaces te implementeren. Elk element moet ten minste één van de interfaces in de eerste tabel in de volgende sectie implementeren. Als het element bovendien een of meer besturingspatronen ondersteunt, moet het de juiste interface implementeren voor elk besturingspatroon.

Uw UI Automation-providerproject moet verwijzen naar de volgende assembly's:

  • UIAutomationProviders.dll

  • UIAutomationTypes.dll

  • WindowsBase.dll

Providerinterfaces

Elke UI Automation-provider moet een van de volgende interfaces implementeren.

Interface Beschrijving
IRawElementProviderSimple Biedt functionaliteit voor een eenvoudig besturingselement dat in een venster wordt gehost, inclusief ondersteuning voor besturingspatronen en eigenschappen.
IRawElementProviderFragment Neemt over van IRawElementProviderSimple: Voegt functionaliteit toe voor een element in een complex besturingselement, inclusief navigatie in het fragment, instellingsfocus en retourneert de begrenzingsrechthoek van het element.
IRawElementProviderFragmentRoot Neemt over van IRawElementProviderFragment: Voegt functionaliteit toe voor het hoofdelement in een complex besturingselement, inclusief het zoeken naar een onderliggend element op opgegeven coördinaten en het instellen van de focusstatus voor het hele besturingselement.

De volgende interfaces bieden extra functionaliteit, maar hoeven niet te worden geïmplementeerd.

Interface Beschrijving
IRawElementProviderAdviseEvents Hiermee kan de provider aanvragen voor gebeurtenissen bijhouden.
IRawElementProviderHwndOverride Hiermee schakelt u de positie van vensterelementen in de UI Automation-structuur van een fragment in.

Alle andere interfaces in de System.Windows.Automation.Provider naamruimte zijn bedoeld voor ondersteuning van besturingspatronen.

Vereisten voor niet-WPF-providers

Als u wilt communiceren met UI Automation, moet uw besturingselement de volgende belangrijke functionaliteitsgebieden implementeren:

Functionaliteit Implementatie
De provider beschikbaar maken voor UI Automation Als reactie op een WM_GETOBJECT bericht dat naar het besturingselementvenster wordt verzonden IRawElementProviderSimple , retourneert u het object dat wordt geïmplementeerd (of een afgeleide interface). Voor fragmenten moet dit de provider zijn voor de hoofdmap van het fragment.
Eigenschapswaarden opgeven Implementeren GetPropertyValue om waarden op te geven of te overschrijven.
De client in staat stellen om met het besturingselement te communiceren Implementeer interfaces die ondersteuning bieden voor besturingspatronen, zoals IInvokeProvider. Retourneer deze patroonproviders in uw implementatie van GetPatternProvider.
Gebeurtenissen genereren Roep een van de statische methoden aan om AutomationInteropProvider een gebeurtenis te genereren waarnaar een client kan luisteren.
Navigatie en focus in een fragment inschakelen Implementeer IRawElementProviderFragment voor elk element in het fragment. (Niet nodig voor elementen die geen deel uitmaken van een fragment.)
Focus en locatie van onderliggend element in een fragment inschakelen Implementeren IRawElementProviderFragmentRoot. (Niet nodig voor elementen die geen fragmentwortels zijn.)

Eigenschapswaarden in niet-WPF-providers

UI Automation-providers voor aangepaste besturingselementen moeten bepaalde eigenschappen ondersteunen die kunnen worden gebruikt door het automatiseringssysteem en door clienttoepassingen. Voor elementen die worden gehost in Windows (HWND's), kan UI Automation bepaalde eigenschappen ophalen van de standaardvensterprovider, maar moet andere van de aangepaste provider worden opgehaald.

Providers voor op HWND gebaseerde besturingselementen hoeven meestal niet de volgende eigenschappen op te geven (geïdentificeerd door veldwaarden):

Notitie

Het RuntimeIdProperty van een eenvoudig element of fragment dat in een venster wordt gehost, wordt verkregen uit het venster. Fragmentelementen onder de hoofdmap (zoals lijstitems in een keuzelijst) moeten echter hun eigen id's opgeven. Zie GetRuntimeId voor meer informatie.

De IsKeyboardFocusableProperty waarde moet worden geretourneerd voor providers die worden gehost in een Besturingselement Windows Forms. In dit geval kan de standaardvensterprovider mogelijk de juiste waarde niet ophalen.

Dit NameProperty wordt meestal geleverd door de hostprovider. Als een aangepast besturingselement bijvoorbeeld is afgeleid van Control, wordt de naam afgeleid van de Text eigenschap van het besturingselement.

Zie Voorbeeldcode: Retoureigenschappen van een UI Automation-provider.

Gebeurtenissen in niet-WPF-providers

UI Automation-providers moeten gebeurtenissen genereren om clienttoepassingen op de hoogte te stellen van wijzigingen in de status van de gebruikersinterface. De volgende methoden worden gebruikt om gebeurtenissen te genereren.

Wijze Description
RaiseAutomationEvent Hiermee worden verschillende gebeurtenissen gegenereerd, waaronder gebeurtenissen die worden geactiveerd door controlepatronen.
RaiseAutomationPropertyChangedEvent Genereert een gebeurtenis wanneer een UI Automation-eigenschap is gewijzigd.
RaiseStructureChangedEvent Hiermee wordt een gebeurtenis gegenereerd wanneer de structuur van de UI Automation-structuur is gewijzigd; Bijvoorbeeld door het verwijderen of toevoegen van een element.

Het doel van een gebeurtenis is om de client op de hoogte te stellen van iets dat plaatsvindt in de gebruikersinterface (UI), ongeacht of de activiteit wordt geactiveerd door het UI Automation-systeem zelf. De gebeurtenis die wordt geïdentificeerd InvokedEvent , moet bijvoorbeeld worden gegenereerd wanneer het besturingselement wordt aangeroepen, hetzij via directe gebruikersinvoer of door de aanroepende Invokeclienttoepassing.

Om de prestaties te optimaliseren, kan een provider selectief gebeurtenissen genereren of helemaal geen gebeurtenissen genereren als er geen clienttoepassing is geregistreerd om ze te ontvangen. De volgende methoden worden gebruikt voor optimalisatie.

Wijze Description
ClientsAreListening Deze statische eigenschap geeft aan of clienttoepassingen zich hebben geabonneerd op UI Automation-gebeurtenissen.
IRawElementProviderAdviseEvents Door de implementatie van deze interface op een fragmenthoofdmap van de provider kan dit worden geadviseerd wanneer clients gebeurtenis-handlers registreren en de registratie van gebeurtenis-handlers voor gebeurtenissen op het fragment ongedaan maken.

Navigatie van niet-WPF-provider

Providers voor eenvoudige besturingselementen, zoals een aangepaste knop die wordt gehost in een venster (HWND), hoeven geen ondersteuning te bieden voor navigatie in de UI Automation-structuur. Navigatie van en naar het element wordt verwerkt door de standaardprovider voor het hostvenster, dat is opgegeven in de implementatie van HostRawElementProvider. Wanneer u echter een provider implementeert voor een complex aangepast besturingselement, moet u navigatie ondersteunen tussen het hoofdknooppunt van het fragment en de onderliggende knooppunten, en tussen knooppunten op hetzelfde niveau.

Notitie

Elementen van een ander fragment dan de hoofdmap moeten een null verwijzing retourneren van HostRawElementProvider, omdat ze niet rechtstreeks in een venster worden gehost en geen standaardprovider navigatie naar en van hen kan ondersteunen.

De structuur van het fragment wordt bepaald door uw implementatie van Navigate. Voor elke mogelijke richting van elk fragment retourneert deze methode het providerobject voor het element in die richting. Als er geen element in die richting is, retourneert de methode een null verwijzing.

De fragmenthoofdmap ondersteunt alleen navigatie naar onderliggende elementen. Een keuzelijst retourneert bijvoorbeeld het eerste item in de lijst wanneer de richting is FirstChilden het laatste item wanneer de richting is LastChild. De hoofdmap van het fragment biedt geen ondersteuning voor navigatie naar een bovenliggende of broers en zussen; dit wordt verwerkt door de hostvensterprovider.

Elementen van een fragment dat niet de hoofdmap is, moeten navigatie naar het bovenliggende item ondersteunen, en voor eventuele broers en zussen en kinderen die ze hebben.

Niet-WPF Provider Reparenting

Pop-upvensters zijn eigenlijk vensters op het hoogste niveau en worden dus standaard weergegeven in de UI Automation-structuur als onderliggende elementen van het bureaublad. In veel gevallen zijn pop-upvensters echter logisch onderliggende elementen van een ander besturingselement. De vervolgkeuzelijst van een keuzelijst met invoervak is bijvoorbeeld logisch een onderliggend element van de keuzelijst met invoervak. Op dezelfde manier is een snelmenu logisch een onderliggend element van het menu. UI Automation biedt ondersteuning voor reparent pop-upvensters, zodat ze lijken te zijn onderliggende elementen van het bijbehorende besturingselement.

Een pop-upvenster weergeven:

  1. Maak een provider voor het pop-upvenster. Hiervoor moet de klasse van het pop-upvenster van tevoren bekend zijn.

  2. Implementeer alle eigenschappen en patronen zoals gebruikelijk voor dat pop-upvenster, alsof het een besturingselement op zichzelf was.

  3. Implementeer de HostRawElementProvider eigenschap zodat deze de waarde retourneert waaruit HostProviderFromHandlede parameter de venstergreep van het pop-upvenster is.

  4. Implementeer Navigate dit voor het pop-upvenster en het bovenliggende venster, zodat navigatie correct wordt verwerkt van het logische bovenliggende element naar de logische onderliggende items en tussen onderliggende onderliggende items.

Wanneer UI Automation het pop-upvenster tegenkomt, wordt herkend dat navigatie wordt overschreven van de standaardinstelling en wordt het pop-upvenster overgeslagen wanneer het wordt aangetroffen als onderliggend element van het bureaublad. In plaats daarvan is het knooppunt alleen bereikbaar via het fragment.

Reparenting is niet geschikt voor gevallen waarin een besturingselement een venster van een klasse kan hosten. Een rebar kan bijvoorbeeld elk type HWND in de banden hosten. Voor het afhandelen van deze gevallen ondersteunt UI Automation een alternatieve vorm van HWND-verplaatsing, zoals beschreven in de volgende sectie.

Verplaatsen van niet-WPF-provider

UI Automation-fragmenten kunnen twee of meer elementen bevatten die elk zijn opgenomen in een venster (HWND). Omdat elke HWND een eigen standaardprovider heeft die van mening is dat de HWND een onderliggend element van een HWND is, worden in de UI Automation-structuur standaard de HWND's in het fragment weergegeven als onderliggende elementen van het bovenliggende venster. In de meeste gevallen is dit wenselijk gedrag, maar soms kan dit leiden tot verwarring omdat het niet overeenkomt met de logische structuur van de gebruikersinterface.

Een goed voorbeeld hiervan is een rebar-besturingselement. Een rebar bevat stroken, die elk op hun beurt een op HWND gebaseerd besturingselement kunnen bevatten, zoals een werkbalk, een invoervak of een keuzelijst met invoervak. De standaardvensterprovider voor de rebar HWND ziet de bandbesturing HWND's als kinderen en de rebarprovider ziet de banden als kinderen. Omdat de HWND-provider en de rebarprovider samenwerken en hun kinderen combineren, worden zowel de banden als de HWND-besturingselementen weergegeven als onderliggende elementen van de rebar. Logisch gezien moeten alleen de banden worden weergegeven als onderliggende elementen van de balk en moet elke bandprovider worden gekoppeld aan de standaard HWND-provider voor het besturingselement dat deze bevat.

Hiervoor maakt de fragmenthoofdprovider voor de rebar een reeks onderliggende elementen beschikbaar die de banden vertegenwoordigen. Elke band heeft één provider waarmee eigenschappen en patronen kunnen worden weergegeven. Bij de implementatie van HostRawElementProvider, retourneert de bandprovider de standaardvensterprovider voor het besturingselement HWND, dat wordt verkregen door aan te roepen HostProviderFromHandle, doorgegeven in de venstergreep van het besturingselement. Ten slotte implementeert de fragmenthoofdprovider voor de rebar de IRawElementProviderHwndOverride interface en retourneert in de implementatie ervan GetOverrideProviderForHwnd de juiste bandprovider voor het besturingselement in de opgegeven HWND.

Zie ook