Implementasi Penyedia UI Automation Sisi Server
Catatan
Dokumentasi ini ditujukan untuk pengembang .NET Framework yang ingin menggunakan kelas UI Automation terkelola yang ditentukan pada namespace System.Windows.Automation. Untuk informasi terbaru tentang UI Automation, lihat API Automasi Windows: Automasi Antarmuka Pengguna.
Bagian ini menjelaskan cara mengimplementasikan penyedia UI Automation sisi server untuk kontrol kustom.
Implementasi untuk elemen Windows Presentation Foundation (WPF) dan elemen non-WPF (seperti yang didesain untuk Formulir Windows) pada dasarnya berbeda. Elemen WPF memberikan dukungan untuk UI Automation melalui kelas yang berasal dari AutomationPeer. Elemen Non-WPF memberikan dukungan melalui implementasi antarmuka penyedia.
Pertimbangan Keamanan
Penyedia harus ditulis sehingga penyedia tersebut dapat bekerja dalam lingkungan kepercayaan parsial. Karena UIAutomationClient.dll tidak dikonfigurasi untuk berjalan dalam kepercayaan parsial, kode penyedia Anda tidak boleh mereferensikan rakitan tersebut. Jika demikian, kode dapat berjalan di lingkungan kepercayaan penuh, tetapi kemudian akan gagal di lingkungan kepercayaan parsial.
Secara khusus, jangan gunakan bidang dari kelas di UIAutomationClient.dll seperti yang ada di AutomationElement. Sebagai gantinya, gunakan bidang yang setara dari kelas di UIAutomationTypes.dll, seperti AutomationElementIdentifiers.
Implementasi Penyedia oleh Elemen Windows Presentation Foundation
Untuk informasi selengkapnya tentang topik ini, lihat UI Automation pada Kontrol Kustom WPF.
Implementasi Penyedia oleh Elemen non-WPF
Kontrol kustom yang bukan merupakan bagian dari kerangka kerja WPF, tetapi ditulis dalam kode terkelola (sering kali adalah kontrol Formulir Windows), memberikan dukungan untuk UI Automation dengan mengimplementasikan antarmuka. Setiap elemen harus mengimplementasikan setidaknya salah satu antarmuka yang tercantum dalam tabel pertama di bagian berikutnya. Selain itu, jika elemen mendukung satu atau lebih pola kontrol, elemen harus mengimplementasikan antarmuka yang sesuai untuk setiap pola kontrol.
Proyek penyedia UI Automation Anda harus mereferensikan rakitan berikut:
UIAutomationProviders.dll
UIAutomationTypes.dll
WindowsBase.dll
Antarmuka Penyedia
Setiap penyedia UI Automation harus mengimplementasikan salah satu antarmuka berikut.
| Antarmuka | Deskripsi |
|---|---|
| IRawElementProviderSimple | Menyediakan fungsionalitas untuk kontrol sederhana yang dihosting di jendela, termasuk dukungan untuk pola dan properti kontrol. |
| IRawElementProviderFragment | Mewarisi dari IRawElementProviderSimple. Menambahkan fungsionalitas untuk elemen dalam kontrol yang kompleks, termasuk navigasi dalam fragmen, mengatur fokus, dan mengembalikan kotak batas elemen. |
| IRawElementProviderFragmentRoot | Mewarisi dari IRawElementProviderFragment. Menambahkan fungsionalitas untuk elemen akar dalam kontrol yang kompleks, termasuk menemukan elemen turunan pada koordinat yang ditentukan dan mengatur status fokus untuk seluruh kontrol. |
Antarmuka berikut menyediakan fungsionalitas tambahan, tetapi tidak perlu diimplementasikan.
| Antarmuka | Deskripsi |
|---|---|
| IRawElementProviderAdviseEvents | Memungkinkan penyedia untuk melacak permintaan kejadian. |
| IRawElementProviderHwndOverride | Memungkinkan reposisi elemen berbasis jendela dalam pohon UI Automation fragmen. |
Semua antarmuka lain di namespace System.Windows.Automation.Provider digunakan untuk dukungan pola kontrol.
Persyaratan untuk Penyedia Non-WPF
Untuk berkomunikasi dengan UI Automation, kontrol Anda harus mengimplementasikan area utama fungsionalitas berikut:
| Fungsi | implementasi |
|---|---|
| Mengekspos penyedia ke UI Automation | Sebagai respons terhadap pesan WM_GETOBJECT yang dikirim ke jendela kontrol, mengembalikan objek yang mengimplementasikan IRawElementProviderSimple (atau antarmuka turunan). Untuk fragmen, implementasi ini harus menjadi penyedia untuk akar fragmen. |
| Menyediakan nilai properti | Implementasikan GetPropertyValue untuk menyediakan atau mengambil alih nilai. |
| Memungkinkan klien untuk berinteraksi dengan kontrol | Mengimplementasikan antarmuka yang mendukung pola kontrol, seperti IInvokeProvider. Mengembalikan penyedia pola ini dalam implementasi GetPatternProvider Anda. |
| Memunculkan kejadian | Memanggil salah satu metode statis AutomationInteropProvider untuk memunculkan kejadian yang dapat didengarkan oleh klien. |
| Memungkinkan navigasi dan pemfokusan dalam fragmen | Mengimplementasikan IRawElementProviderFragment untuk setiap elemen dalam fragmen. (Tidak diperlukan untuk elemen yang bukan merupakan bagian dari fragmen.) |
| Memungkinkan pemfokusan dan lokasi elemen turunan dalam fragmen | Mengimplementasikan IRawElementProviderFragmentRoot. (Tidak diperlukan untuk elemen yang bukan merupakan akar dari fragmen.) |
Nilai Properti di Penyedia Non-WPF
Penyedia Automation UI untuk kontrol kustom harus mendukung properti tertentu yang dapat digunakan oleh sistem automasi serta oleh aplikasi klien. Untuk elemen yang dihosting di jendela (HWND), UI Automation dapat mengambil beberapa properti dari penyedia jendela default, tetapi UI Automation harus memperoleh properti lainnya dari penyedia kustom.
Penyedia untuk kontrol berbasis HWND biasanya tidak perlu menyediakan properti berikut (diidentifikasi berdasarkan nilai bidang):
Catatan
RuntimeIdProperty dari elemen sederhana atau akar fragmen yang dihosting di jendela diperoleh dari jendela; namun, elemen fragmen di bawah akar (seperti item daftar dalam kotak daftar) harus menyediakan pengidentifikasinya sendiri. Untuk informasi selengkapnya, lihat GetRuntimeId .
IsKeyboardFocusableProperty harus dikembalikan untuk penyedia yang dihosting dalam kontrol Formulir Windows. Dalam kasus ini, penyedia jendela default mungkin tidak dapat mengambil nilai yang benar.
NameProperty biasanya disediakan oleh penyedia host. Misalnya, jika kontrol kustom berasal dari Control, namanya akan berasal dari properti Text kontrol.
Untuk contoh kode, lihat Mengembalikan Properti dari Penyedia UI Automation.
Kejadian di Penyedia Non-WPF
Penyedia UI Automation harus memunculkan kejadian untuk memberi tahu aplikasi klien tentang perubahan status UI. Metode berikut digunakan untuk memunculkan kejadian.
| Metode | Deskripsi |
|---|---|
| RaiseAutomationEvent | Memunculkan berbagai kejadian, termasuk kejadian yang dipicu oleh pola kontrol. |
| RaiseAutomationPropertyChangedEvent | Memunculkan kejadian ketika properti UI Automation telah berubah. |
| RaiseStructureChangedEvent | Memunculkan kejadian ketika struktur pohon UI Automation telah berubah; misalnya, dengan penghapusan atau penambahan elemen. |
Tujuan dari kejadian adalah untuk memberi tahu klien tentang sesuatu yang terjadi di antarmuka pengguna (UI), untuk mengetahui jika aktivitas dipicu oleh sistem UI Automation itu sendiri atau tidak. Misalnya, kejadian yang diidentifikasi oleh InvokedEvent harus dimunculkan setiap kali kontrol dipanggil, baik melalui input pengguna langsung atau dengan panggilan aplikasi klien Invoke.
Untuk mengoptimalkan performa, penyedia dapat secara selektif memunculkan kejadian, atau tidak memunculkan kejadian sama sekali jika tidak ada aplikasi klien yang terdaftar untuk menerimanya. Metode berikut digunakan untuk pengoptimalan.
| Metode | Deskripsi |
|---|---|
| ClientsAreListening | Properti statis ini menentukan jika ada aplikasi klien telah berlangganan kejadian UI Automation. |
| IRawElementProviderAdviseEvents | Implementasi penyedia terhadap antarmuka pada akar fragmen memungkinkannya untuk diberi saran ketika klien mendaftar dan membatalkan pendaftaran penanganan aktivitas untuk kejadian pada fragmen. |
Navigasi Penyedia Non-WPF
Penyedia untuk kontrol sederhana seperti tombol kustom yang dihosting di jendela (HWND) tidak perlu mendukung navigasi dalam pohon UI Automation. Navigasi ke dan dari elemen ditangani oleh penyedia default untuk jendela host, yang ditentukan dalam implementasi HostRawElementProvider. Namun, ketika Anda mengimplementasikan penyedia untuk kontrol kustom yang kompleks, Anda harus mendukung navigasi antara simpul akar fragmen dengan turunannya serta di antara simpul relasi.
Catatan
Elemen fragmen selain akar harus mengembalikan referensi null dari HostRawElementProvider, karena elemen tersebut tidak dihosting secara langsung di jendela dan tidak ada penyedia default yang dapat mendukung navigasi ke dan dari elemen tersebut.
Struktur fragmen ditentukan oleh implementasi Navigate Anda. Untuk setiap kemungkinan arah dari setiap fragmen, metode ini mengembalikan objek penyedia untuk elemen di arah tersebut. Jika tidak terdapat elemen di arah tersebut, metode mengembalikan referensi null.
Akar fragmen hanya mendukung navigasi ke elemen turunan. Misalnya, kotak daftar mengembalikan item pertama dalam daftar ketika arahnya adalah FirstChild dan item terakhir ketika arahnya adalah LastChild. Akar fragmen tidak mendukung navigasi ke induk atau relasi; akar fragmen ditangani oleh penyedia jendela host.
Elemen fragmen yang bukan merupakan akar harus mendukung navigasi ke induk dan ke setiap relasi serta turunan yang mereka miliki.
Pengindukan Ulang Penyedia Non-WPF
Jendela pop-up sebenarnya merupakan jendela tingkat atas dan secara default muncul di pohon UI Automation sebagai turunan desktop. Namun, dalam banyak kasus, jendela pop-up secara logis merupakan turunan dari beberapa kontrol lain. Misalnya, daftar drop-down kotak kombo secara logis merupakan turunan kotak kombo tersebut. Demikian pula jendela pop-up menu secara logis merupakan turunan menu tersebut. UI Automation menyediakan dukungan untuk mengindukkan ulang jendela pop-up sehingga jendela tersebut tampak seperti turunan dari kontrol terkait.
Untuk mengindukkan ulang jendela pop-up:
Buat penyedia untuk jendela pop-up. Proses ini mengharuskan kelas jendela pop-up diketahui terlebih dahulu.
Implementasikan semua properti dan pola seperti biasa untuk pop-up tersebut, seolah-olah itu adalah kontrolnya sendiri.
Implementasikan properti HostRawElementProvider sehingga properti tersebut mengembalikan nilai yang diperoleh dari HostProviderFromHandle, yang parameternya adalah handel jendela dari jendela pop-up.
Implementasikan Navigate untuk jendela pop-up dan induknya sehingga navigasi ditangani dengan benar dari induk logis ke turunan logis, serta antara turunan relasi.
Ketika UI Automation mendapati jendela pop-up, UI Automation akan mengenali jika navigasi diambil alih dari default, dan melompati jendela pop-up ketika didapati sebagai turunan desktop. Sebagai gantinya, simpul hanya akan dapat dijangkau melalui fragmen.
Pengindukan ulang tidak cocok untuk kasus ketika kontrol dapat menghosting jendela kelas apa pun. Misalnya, bilah ulang dapat meng-hosting jenis HWND apa pun dalam pitanya. Untuk menangani kasus ini, UI Automation mendukung bentuk alternatif relokasi HWND, seperti yang dijelaskan pada bagian berikutnya.
Reposisi Penyedia Non-WPF
Fragmen UI Automation mungkin berisi dua atau lebih elemen yang masing-masing terdapat di jendela (HWND). Karena setiap HWND memiliki penyedia default-nya sendiri yang menganggap HWND sebagai turunan dari isi HWND, pohon UI Automation akan secara default menunjukkan HWND dalam fragmen sebagai turunan dari jendela induk. Dalam kebanyakan kasus, ini adalah perilaku yang diinginkan, tetapi terkadang dapat menyebabkan kebingungan karena ketidakcocokan dengan struktur logis dari UI tersebut.
Contoh yang baik dari kasus ini adalah kontrol bilah ulang. Bilah ulang berisi pita yang masing-masing dapat berisi kontrol berbasis HWND seperti bar alat, kotak edit, atau kotak kombo. Penyedia jendela default untuk biah ulang HWND melihat kontrol pita HWND sebagai turunan, dan penyedia bilah ulang melihat pita tersebut sebagai turunan. Karena penyedia HWND dan penyedia bilah ulang bekerja secara bersamaan serta menggabungkan turunannya, baik pita maupun kontrol berbasis HWND muncul sebagai turunan dari bilah ulang. Namun, secara logis, hanya pita yang akan muncul sebagai turunan dari bilah ulang, dan setiap penyedia pita harus digabungkan dengan penyedia HWND default untuk kontrol yang dimuatnya.
Untuk mencapainya, penyedia akar fragmen untuk bilah ulang akan mengekspos kumpulan turunan yang menunjukkan pita. Setiap pita memiliki satu penyedia yang dapat mengekspos properti dan pola. Dalam pengimplementasian HostRawElementProvider, penyedia pita mengembalikan penyedia jendela default untuk kontrol HWND, yang diperolehnya dengan memanggil HostProviderFromHandle, melewati handel jendela kontrol. Terakhir, penyedia akar fragmen untuk bilah akan mengimplementasikan antarmuka IRawElementProviderHwndOverride, dan dalam pengimplementasian GetOverrideProviderForHwnd, penyedia tersebut mengembalikan penyedia pita yang sesuai untuk kontrol yang terdapat dalam HWND yang telah ditentukan.