Implementacja dostawcy automatyzacji interfejsu użytkownika po stronie serweraServer-Side UI Automation Provider Implementation

Uwaga

Ta dokumentacja jest przeznaczona dla .NET Framework deweloperów, którzy chcą korzystać z zarządzanych Automatyzacja interfejsu użytkownikaUI Automation klas zdefiniowanych w System.Windows.Automation przestrzeni nazw.This documentation is intended for .NET Framework developers who want to use the managed Automatyzacja interfejsu użytkownikaUI Automation classes defined in the System.Windows.Automation namespace. Aby uzyskać najnowsze informacje na temat Automatyzacja interfejsu użytkownikaUI Automation , zobacz interfejs API usługi Windows Automation: Automatyzacja interfejsu użytkownika.For the latest information about Automatyzacja interfejsu użytkownikaUI Automation, see Windows Automation API: UI Automation.

W tej sekcji opisano sposób implementacji dostawcy automatyzacji interfejsu użytkownika po stronie serwera dla kontrolki niestandardowej.This section describes how to implement a server-side UI Automation provider for a custom control.

Implementacja elementów Windows Presentation Foundation (WPF) i elementów innych niż WPF (takich jak te zaprojektowane dla Windows Forms) różni się zasadniczo.The implementation for Windows Presentation Foundation (WPF) elements and non-WPF elements (such as those designed for Windows Forms) is fundamentally different. Elementy WPF zapewniają obsługę Automatyzacja interfejsu użytkownikaUI Automation za pośrednictwem klasy pochodnej AutomationPeer .WPF elements provide support for Automatyzacja interfejsu użytkownikaUI Automation through a class derived from AutomationPeer. Elementy inne niż WPF zapewniają obsługę za pomocą implementacji interfejsów dostawcy.Non-WPF elements provide support through implementations of provider interfaces.

Zagadnienia dotyczące bezpieczeństwaSecurity Considerations

Należy napisać dostawców, aby mogły one działać w środowisku częściowego zaufania.Providers should be written so that they can work in a partial-trust environment. Ponieważ UIAutomationClient.dll nie jest skonfigurowany do uruchamiania w ramach częściowej relacji zaufania, kod dostawcy nie powinien odwoływać się do tego zestawu.Because UIAutomationClient.dll is not configured to run under partial trust, your provider code should not reference that assembly. W takim przypadku kod może działać w środowisku z pełnym zaufaniem, ale kończy się niepowodzeniem w środowisku częściowego zaufania.If it does so, the code may run in a full-trust environment but then fail in a partial-trust environment.

W szczególności nie należy używać pól z klas w UIAutomationClient.dll, takich jak te w AutomationElement .In particular, do not use fields from classes in UIAutomationClient.dll such as those in AutomationElement. Zamiast tego należy użyć odpowiednich pól z klas w UIAutomationTypes.dll, takich jak AutomationElementIdentifiers .Instead, use the equivalent fields from classes in UIAutomationTypes.dll, such as AutomationElementIdentifiers.

Implementacja dostawcy przez Windows Presentation Foundation elementyProvider Implementation by Windows Presentation Foundation Elements

Aby uzyskać więcej informacji na temat tego tematu, zobacz Automatyzacja interfejsu użytkownika dla kontrolki NIESTANDARDOWEJ WPF.For more information on this topic, please see UI Automation of a WPF Custom Control.

Implementacja dostawcy przez elementy inne niż WPFProvider Implementation by non-WPF Elements

Niestandardowe kontrolki, które nie są częścią platformy WPF Framework, ale są zapisywane w kodzie zarządzanym (najczęściej są to Windows Forms kontrolki), zapewniają obsługę Automatyzacja interfejsu użytkownikaUI Automation przez Implementowanie interfejsów.Custom controls that are not part of the WPF framework, but that are written in managed code (most often these are Windows Forms controls), provide support for Automatyzacja interfejsu użytkownikaUI Automation by implementing interfaces. Każdy element musi implementować co najmniej jeden interfejs wymieniony w pierwszej tabeli w następnej sekcji.Every element must implement at least one of the interfaces listed in the first table in the next section. Ponadto, jeśli element obsługuje jeden lub więcej wzorców kontrolek, musi zaimplementować odpowiedni interfejs dla każdego wzorca kontroli.In addition, if the element supports one or more control patterns, it must implement the appropriate interface for each control pattern.

Automatyzacja interfejsu użytkownikaUI AutomationProjekt dostawcy musi odwoływać się do następujących zestawów:Your Automatyzacja interfejsu użytkownikaUI Automation provider project must reference the following assemblies:

  • UIAutomationProviders.dllUIAutomationProviders.dll

  • UIAutomationTypes.dllUIAutomationTypes.dll

  • WindowsBase.dllWindowsBase.dll

Interfejsy dostawcyProvider Interfaces

Każdy Automatyzacja interfejsu użytkownikaUI Automation dostawca musi implementować jeden z następujących interfejsów.Every Automatyzacja interfejsu użytkownikaUI Automation provider must implement one of the following interfaces.

InterfejsInterface OpisDescription
IRawElementProviderSimple Oferuje funkcje prostej kontrolki hostowanej w oknie, w tym obsługę wzorców i właściwości formantów.Provides functionality for a simple control hosted in a window, including support for control patterns and properties.
IRawElementProviderFragment Dziedziczy z IRawElementProviderSimple .Inherits from IRawElementProviderSimple. Dodaje funkcje dla elementu w kontrolce złożonej, w tym nawigację w obrębie fragmentu, ustawienie fokusu i zwrócenie obwiedni elementu.Adds functionality for an element in a complex control, including navigation within the fragment, setting focus, and returning the bounding rectangle of the element.
IRawElementProviderFragmentRoot Dziedziczy z IRawElementProviderFragment .Inherits from IRawElementProviderFragment. Dodaje funkcje dla elementu głównego w kontrolce złożonej, w tym lokalizowanie elementu podrzędnego w określonych współrzędnych i Ustawianie stanu fokusu dla całej kontrolki.Adds functionality for the root element in a complex control, including locating a child element at specified coordinates and setting the focus state for the entire control.

Poniższe interfejsy oferują dodane funkcje, ale nie są wymagane do wdrożenia.The following interfaces provide added functionality but are not required to be implemented.

InterfejsInterface OpisDescription
IRawElementProviderAdviseEvents Umożliwia dostawcy śledzenie żądań zdarzeń.Enables the provider to track requests for events.
IRawElementProviderHwndOverride Umożliwia zmianę położenia elementów opartych na oknach w Automatyzacja interfejsu użytkownikaUI Automation drzewie fragmentu.Enables repositioning of window-based elements within the Automatyzacja interfejsu użytkownikaUI Automation tree of a fragment.

Wszystkie inne interfejsy w System.Windows.Automation.Provider przestrzeni nazw są przeznaczone do obsługi wzorców kontrolek.All other interfaces in the System.Windows.Automation.Provider namespace are for control pattern support.

Wymagania dla dostawców nienależących do platformy WPFRequirements for Non-WPF Providers

W celu komunikowania się z programem Automatyzacja interfejsu użytkownikaUI Automation Kontrola musi implementować następujące główne obszary funkcjonalności:In order to communicate with Automatyzacja interfejsu użytkownikaUI Automation, your control must implement the following main areas of functionality:

FunkcjonalnośćFunctionality ImplementacjaImplementation
Uwidacznianie dostawcy Automatyzacja interfejsu użytkownikaUI AutomationExpose the provider to Automatyzacja interfejsu użytkownikaUI Automation W odpowiedzi na WM_GETOBJECT komunikat wysyłany do okna sterowania zwracają obiekt implementujący IRawElementProviderSimple (lub interfejs pochodny).In response to a WM_GETOBJECT message sent to the control window, return the object that implements IRawElementProviderSimple (or a derived interface). Dla fragmentów, musi to być dostawca dla katalogu głównego fragmentów.For fragments, this must be the provider for the fragment root.
Podaj wartości właściwościProvide property values Zaimplementuj GetPropertyValue , aby podać lub zastąpić wartości.Implement GetPropertyValue to provide or override values.
Zezwalaj klientowi na współpracującie z kontrolkąEnable the client to interact with the control Implementuj interfejsy obsługujące wzorce kontroli, takie jak IInvokeProvider .Implement interfaces that support control patterns, such as IInvokeProvider. Zwróć tych dostawców wzorców w implementacji programu GetPatternProvider .Return these pattern providers in your implementation of GetPatternProvider.
Zgłoś zdarzeniaRaise events Wywołaj jedną z metod statycznych, AutomationInteropProvider Aby zgłosić zdarzenie, dla którego klient może nasłuchiwać.Call one of the static methods of AutomationInteropProvider to raise an event that a client can listen for.
Włączanie nawigacji i skoncentrowanie się na fragmentachEnable navigation and focusing within a fragment Zaimplementuj IRawElementProviderFragment dla każdego elementu w fragmencie.Implement IRawElementProviderFragment for each element within the fragment. (Niepotrzebne dla elementów, które nie są częścią fragmentu).(Not necessary for elements that are not part of a fragment.)
Włącz skoncentrowanie i lokalizację elementu podrzędnego w fragmencieEnable focusing and location of child element in a fragment Implementacja IRawElementProviderFragmentRoot .Implement IRawElementProviderFragmentRoot. (Niepotrzebne dla elementów, które nie mają fragmentów głównych).(Not necessary for elements that are not fragment roots.)

Wartości właściwości w dostawcach spoza WPFProperty Values in Non-WPF Providers

Automatyzacja interfejsu użytkownikaUI Automation dostawcy formantów niestandardowych muszą obsługiwać pewne właściwości, które mogą być używane przez system automatyzacji, a także przez aplikacje klienckie.providers for custom controls must support certain properties that can be used by the automation system as well as by client applications. W przypadku elementów, które są hostowane w systemie Windows (HWND), program Automatyzacja interfejsu użytkownikaUI Automation może pobrać niektóre właściwości z domyślnego dostawcy okien, ale muszą uzyskać innych od dostawcy niestandardowego.For elements that are hosted in windows (HWNDs), Automatyzacja interfejsu użytkownikaUI Automation can retrieve some properties from the default window provider, but must obtain others from the custom provider.

Dostawcy formantów opartych na HWND nie muszą zazwyczaj podawać następujących właściwości (identyfikowanych przez wartości pól):Providers for HWND based controls do not usually need to provide the following properties (identified by field values):

Uwaga

W oknie RuntimeIdProperty uzyskano prosty element lub fragment, który znajduje się w oknie, ale elementy fragmentów znajdujące się poniżej elementu głównego (takie jak elementy listy w polu listy) muszą podawać własne identyfikatory.The RuntimeIdProperty of a simple element or fragment root hosted in a window is obtained from the window; however, fragment elements below the root (such as list items in a list box) must provide their own identifiers. Aby uzyskać więcej informacji, zobacz GetRuntimeId.For more information, see GetRuntimeId.

IsKeyboardFocusablePropertyPowinna zostać zwrócona dla dostawców hostowanych w kontrolce Windows Forms.The IsKeyboardFocusableProperty should be returned for providers hosted in a Windows Forms control. W takim przypadku domyślny dostawca okna może nie być w stanie pobrać poprawnej wartości.In this case, the default window provider may be unable to retrieve the correct value.

NamePropertyJest zazwyczaj dostarczany przez dostawcę hosta.The NameProperty is usually supplied by the host provider. Na przykład, Jeśli kontrolka niestandardowa pochodzi od Control , nazwa pochodzi od Text właściwości formantu.For example, if a custom control is derived from Control, the name is derived from the Text property of the control.

Na przykład kod, zobacz zwracają właściwości z dostawcy automatyzacji interfejsu użytkownika.For example code, see Return Properties from a UI Automation Provider.

Zdarzenia w dostawcach innych niż WPFEvents in Non-WPF Providers

Automatyzacja interfejsu użytkownikaUI Automation dostawcy powinni zgłaszać zdarzenia w celu powiadomienia aplikacji klienckich o zmianach w stanie interfejsu użytkownika.providers should raise events to notify client applications of changes in the state of the UI. Następujące metody są używane do wywoływania zdarzeń.The following methods are used to raise events.

MetodaMethod OpisDescription
RaiseAutomationEvent Wywołuje różne zdarzenia, w tym zdarzenia wyzwalane przez wzorce kontrolek.Raises various events, including events triggered by control patterns.
RaiseAutomationPropertyChangedEvent Podnosi zdarzenie po Automatyzacja interfejsu użytkownikaUI Automation zmianie właściwości.Raises an event when a Automatyzacja interfejsu użytkownikaUI Automation property has changed.
RaiseStructureChangedEvent Podnosi zdarzenie po Automatyzacja interfejsu użytkownikaUI Automation zmianie struktury drzewa, na przykład przez usunięcie lub dodanie elementu.Raises an event when the structure of the Automatyzacja interfejsu użytkownikaUI Automation tree has changed; for example, by the removal or addition of an element.

Celem zdarzenia jest powiadomienie klienta o jakimś miejscu interfejs użytkownika (UI)user interface (UI) , niezależnie od tego, czy działanie jest wyzwalane przez Automatyzacja interfejsu użytkownikaUI Automation sam system.The purpose of an event is to notify the client of something taking place in the interfejs użytkownika (UI)user interface (UI), whether or not the activity is triggered by the Automatyzacja interfejsu użytkownikaUI Automation system itself. Na przykład zdarzenie identyfikowane przez InvokedEvent powinna być wywoływane za każdym razem, gdy kontrolka jest wywoływana, przez bezpośrednie dane wejściowe użytkownika lub przez wywołanie aplikacji klienckiej Invoke .For example, the event identified by InvokedEvent should be raised whenever the control is invoked, either through direct user input or by the client application calling Invoke.

Aby zoptymalizować wydajność, dostawca może wybiórczo zgłaszać zdarzenia lub nie zgłaszać żadnych zdarzeń, jeśli żadna aplikacja kliencka nie zostanie zarejestrowana.To optimize performance, a provider can selectively raise events, or raise no events at all if no client application is registered to receive them. Następujące metody są używane do optymalizacji.The following methods are used for optimization.

MetodaMethod OpisDescription
ClientsAreListening Ta właściwość statyczna określa, czy wszystkie aplikacje klienckie subskrybują Automatyzacja interfejsu użytkownikaUI Automation zdarzenia.This static property specifies whether any client applications have subscribed to Automatyzacja interfejsu użytkownikaUI Automation events.
IRawElementProviderAdviseEvents Implementacja tego interfejsu w ramach dostawcy w katalogu głównym fragmentów umożliwia jego doradzanie, gdy klienci rejestrują i wyrejestrowujeją programy obsługi zdarzeń dla zdarzeń w fragmencie.The provider's implementation of this interface on a fragment root enables it to be advised when clients register and unregister event handlers for events on the fragment.

Nawigacja dostawcy spoza WPFNon-WPF Provider Navigation

Dostawcy formantów prostych, takich jak niestandardowy przycisk hostowany w oknie (HWND), nie muszą obsługiwać nawigowania w obrębie Automatyzacja interfejsu użytkownikaUI Automation drzewa.Providers for simple controls such as a custom button hosted in a window (HWND) do not need to support navigation within the Automatyzacja interfejsu użytkownikaUI Automation tree. Nawigacja do i z elementu jest obsługiwana przez domyślnego dostawcę okna hosta, który jest określony w implementacji HostRawElementProvider .Navigation to and from the element is handled by the default provider for the host window, which is specified in the implementation of HostRawElementProvider. W przypadku zaimplementowania dostawcy dla złożonej kontrolki niestandardowej, należy jednak obsługiwać nawigację między węzłem głównym fragmentu i jego elementami podrzędnymi oraz między węzłami elementów równorzędnych.When you implement a provider for a complex custom control, however, you must support navigation between the root node of the fragment and its descendants, and between sibling nodes.

Uwaga

Elementy fragmentu innego niż główny muszą zwracać null odwołanie z HostRawElementProvider , ponieważ nie są bezpośrednio hostowane w oknie, a żaden dostawca domyślny nie może obsługiwać nawigowania do i z nich.Elements of a fragment other than the root must return a null reference from HostRawElementProvider, because they are not directly hosted in a window, and no default provider can support navigation to and from them.

Struktura fragmentu jest określana przez implementację programu Navigate .The structure of the fragment is determined by your implementation of Navigate. Dla każdego możliwego kierunku z każdego fragmentu ta metoda zwraca obiekt dostawcy dla elementu w tym kierunku.For each possible direction from each fragment, this method returns the provider object for the element in that direction. Jeśli w tym kierunku nie ma elementu, metoda zwraca null odwołanie.If there is no element in that direction, the method returns a null reference.

Element główny fragmentu obsługuje nawigację tylko do elementów podrzędnych.The fragment root supports navigation only to child elements. Na przykład pole listy zwraca pierwszy element na liście, gdy kierunek jest FirstChild i ostatni element, gdy kierunek jest LastChild .For example, a list box returns the first item in the list when the direction is FirstChild, and the last item when the direction is LastChild. Element główny fragmentu nie obsługuje nawigacji do elementów nadrzędnych ani równorzędnych; jest to obsługiwane przez dostawcę okna hosta.The fragment root does not support navigation to a parent or siblings; this is handled by the host window provider.

Elementy fragmentu, który nie jest elementem głównym, muszą obsługiwać nawigację do elementu nadrzędnego oraz do wszelkich elementów równorzędnych i ich elementów podrzędnych.Elements of a fragment that are not the root must support navigation to the parent, and to any siblings and children they have.

Obiekt nadrzędny dostawcy spoza platformy WPFNon-WPF Provider Reparenting

Okna podręczne są w rzeczywistości oknami najwyższego poziomu, a więc domyślnie są wyświetlane w Automatyzacja interfejsu użytkownikaUI Automation drzewie jako elementy podrzędne pulpitu.Pop-up windows are actually top-level windows, and so by default appear in the Automatyzacja interfejsu użytkownikaUI Automation tree as children of the desktop. W wielu przypadkach okna podręczne są jednak logicznie elementami podrzędnymi innej kontrolki.In many cases, however, pop-up windows are logically children of some other control. Na przykład lista rozwijana pola kombi jest logicznie elementem podrzędnym pola kombi.For example, the drop-down list of a combo box is logically a child of the combo box. Analogicznie, okno podręczne menu jest logicznie elementem podrzędnym menu.Similarly, a menu pop-up window is logically a child of the menu. Automatyzacja interfejsu użytkownikaUI Automation zapewnia pomoc techniczną do ponownego nadrzędnego wyskakujących okienek, aby były one elementami podrzędnymi powiązanej kontrolki.provides support to reparent pop-up windows so that they appear to be children of the associated control.

Aby zmienić nadrzędny okna podręcznego:To reparent a pop-up window:

  1. Utwórz dostawcę dla okna podręcznego.Create a provider for the pop-up window. Wymaga to, aby Klasa okna podręcznego była znana z góry.This requires that the class of the pop-up window is known in advance.

  2. Zaimplementuj wszystkie właściwości i wzorce w zwykły sposób dla tego okna podręcznego, tak jakby były one kontrolką we własnym zakresie.Implement all properties and patterns as usual for that pop-up, as though it were a control in its own right.

  3. Zaimplementuj HostRawElementProvider Właściwość, aby zwracała wartość uzyskaną z HostProviderFromHandle , gdzie parametr jest dojściem okna podręcznego.Implement the HostRawElementProvider property so that it returns the value obtained from HostProviderFromHandle, where the parameter is the window handle of the pop-up window.

  4. Zaimplementuj Navigate dla okna podręcznego i jego elementu nadrzędnego, aby Nawigacja była prawidłowo obsługiwana z logicznego elementu nadrzędnego do logicznych elementów podrzędnych i między równorzędnymi elementami podrzędnymi.Implement Navigate for the pop-up window and its parent so that navigation is handled properly from the logical parent to the logical children, and between sibling children.

Gdy Automatyzacja interfejsu użytkownikaUI Automation pojawia się okno podręczne, rozpoznaje, że nawigacja jest zastępowana domyślnie, i pomija okna podręcznego, gdy zostanie on wyświetlony jako element podrzędny pulpitu.When Automatyzacja interfejsu użytkownikaUI Automation encounters the pop-up window, it recognizes that navigation is being overridden from the default, and skips over the pop-up window when it is encountered as a child of the desktop. Zamiast tego węzeł będzie dostępny tylko za pomocą fragmentu.Instead, the node will only be reachable through the fragment.

Obiekt nadrzędny nie jest odpowiedni dla przypadków, gdy kontrolka może obsługiwać okno dowolnej klasy.Reparenting is not suitable for cases where a control can host a window of any class. Na przykład paska pomocniczego może hostować dowolny typ HWND w swoich pasmach.For example, a rebar can host any type of HWND in its bands. Aby obsłużyć te przypadki, program Automatyzacja interfejsu użytkownikaUI Automation obsługuje alternatywną formę relokacji elementu HWND, jak opisano w następnej sekcji.To handle these cases, Automatyzacja interfejsu użytkownikaUI Automation supports an alternative form of HWND relocation, as described in the next section.

Zmiana położenia dostawcy spoza WPFNon-WPF Provider Repositioning

Automatyzacja interfejsu użytkownikaUI Automation fragmenty mogą zawierać co najmniej dwa elementy, które są zawarte w oknie (HWND).fragments may contain two or more elements that are each contained in a window (HWND). Ponieważ każdy HWND ma własnego domyślnego dostawcę, który uważa, że właściwość HWND ma być elementem podrzędnym zawierającej HWND, Automatyzacja interfejsu użytkownikaUI Automation drzewo domyślnie pokaże HWND w fragmencie jako elementy podrzędne okna nadrzędnego.Because each HWND has its own default provider that considers the HWND to be a child of a containing HWND, the Automatyzacja interfejsu użytkownikaUI Automation tree will, by default, show the HWNDs in the fragment as children of the parent window. W większości przypadków jest to pożądane zachowanie, ale czasami może prowadzić do pomyłki, ponieważ nie pasuje do struktury logicznej Interfejs użytkownikaUI .In most cases this is desirable behavior, but sometimes it can lead to confusion because it does not match the logical structure of the Interfejs użytkownikaUI.

Dobrym przykładem jest formant paska pomocniczego.A good example of this is a rebar control. Paska pomocniczego zawiera pasma, z których każdy może z kolei zawierać kontrolkę opartą na elemencie HWND, taką jak pasek narzędzi, pole edycji lub pole kombi.A rebar contains bands, each of which can in turn contain an HWND-based control such as a toolbar, an edit box, or a combo box. Domyślny dostawca okna dla paska pomocniczego HWND widzi kontrolki przedziału jako elementy podrzędne, a dostawca paska pomocniczego widzi paski jako elementy podrzędne.The default window provider for the rebar HWND sees the band control HWNDs as children, and the rebar provider sees the bands as children. Ze względu na to, że dostawca HWND i dostawca paska pomocniczego działają wspólnie i łącząc ich elementy podrzędne, zarówno te, jak i kontrolki oparte na elemencie HWND, są wyświetlane jako elementy podrzędne paska pomocniczego.Because the HWND provider and the rebar provider are working in tandem and combining their children, both the bands and the HWND-based controls appear as children of the rebar. Logicznie jednak tylko paski powinny być wyświetlane jako elementy podrzędne paska pomocniczego, a każdy dostawca pasm powinien być połączony z domyślnym dostawcą HWND dla kontrolki, która zawiera.Logically, however, only the bands should appear as children of the rebar, and each band provider should be coupled with the default HWND provider for the control it contains.

Aby to osiągnąć, główny dostawca fragmentów dla paska pomocniczego uwidacznia zestaw elementów podrzędnych reprezentujących pasma.To accomplish this, the fragment root provider for the rebar exposes a set of children representing the bands. Każda grupa ma jednego dostawcę, który może uwidaczniać właściwości i wzorce.Each band has a single provider that may expose properties and patterns. W jego implementacji HostRawElementProvider dostawca pasma zwraca domyślnego dostawcę okna dla elementu HWND formantu, który uzyskuje przez wywołanie HostProviderFromHandle , przekazanie do uchwytu okna kontrolki.In its implementation of HostRawElementProvider, the band provider returns the default window provider for the control HWND, which it obtains by calling HostProviderFromHandle, passing in the control's window handle. Na koniec główny dostawca fragmentów paska pomocniczego implementuje IRawElementProviderHwndOverride interfejs, a w jego implementacji GetOverrideProviderForHwnd zwraca odpowiedniego dostawcę pasma dla kontrolki zawartej w określonym elemencie HWND.Finally, the fragment root provider for the rebar implements the IRawElementProviderHwndOverride interface, and in its implementation of GetOverrideProviderForHwnd it returns the appropriate band provider for the control contained in the specified HWND.

Zobacz takżeSee also