Membuat Penyedia Properti Windows PowerShell

Topik ini menjelaskan cara membuat penyedia yang memungkinkan pengguna memanipulasi properti item di penyimpanan data. Akibatnya, jenis penyedia ini disebut sebagai penyedia properti Windows PowerShell. Misalnya, penyedia Registri yang disediakan oleh Windows PowerShell menangani nilai kunci registri sebagai properti item kunci registri. Jenis penyedia ini harus menambahkan antarmuka System.Management.Automation.Provider.IPropertyCmdletProvider ke implementasi kelas .NET.

Nota

Windows PowerShell menyediakan file templat yang dapat Anda gunakan untuk mengembangkan penyedia Windows PowerShell. File TemplateProvider.cs tersedia di Kit Pengembangan Perangkat Lunak Microsoft Windows untuk Komponen Runtime Windows Vista dan .NET Framework 3.0. Untuk petunjuk pengunduhan, lihat Cara Menginstal Windows PowerShell dan Mengunduh Windows PowerShell SDK. Templat yang diunduh tersedia di <direktori Sampel> PowerShell. Anda harus membuat salinan file ini dan menggunakan salinan untuk membuat penyedia Windows PowerShell baru, menghapus fungsionalitas apa pun yang tidak Anda perlukan. Untuk informasi selengkapnya tentang implementasi penyedia Windows PowerShell lainnya, lihat Merancang Penyedia Windows PowerShell Anda.

Perhatian

Metode penyedia properti Anda harus menulis objek apa pun menggunakan metode System.Management.Automation.Provider.CmdletProvider.Writepropertyobject*.

Mendefinisikan penyedia Windows PowerShell

Penyedia properti harus membuat kelas .NET yang mendukung antarmuka System.Management.Automation.Provider.IPropertyCmdletProvider . Berikut adalah deklarasi kelas default dari file TemplateProvider.cs yang disediakan oleh Windows PowerShell.

Mendefinisikan Fungsionalitas Dasar

Antarmuka System.Management.Automation.Provider.IPropertyCmdletProvider dapat dilampirkan ke salah satu kelas dasar penyedia, dengan pengecualian kelas System.Management.Automation.Provider.DriveCmdletProvider . Tambahkan fungsionalitas dasar yang diperlukan oleh kelas dasar yang Anda gunakan. Untuk informasi selengkapnya tentang kelas dasar, lihat Merancang Penyedia Windows PowerShell Anda.

Mengambil Properti

Untuk mengambil properti, penyedia harus mengimplementasikan metode System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* untuk mendukung panggilan dari Get-ItemProperty cmdlet. Metode ini mengambil properti item yang terletak di jalur internal penyedia yang ditentukan (memenuhi syarat sepenuhnya).

Parameter menunjukkan providerSpecificPickList properti mana yang akan diambil. Jika parameter ini atau null kosong, metode harus mengambil semua properti. Selain itu, System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* menulis instans objek System.Management.Automation.PSObject yang mewakili kantong properti dari properti yang diambil. Metode ini seharusnya tidak mengembalikan apa-apa.

Disarankan agar implementasi System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* mendukung perluasan nama properti karakter pengganti untuk setiap elemen dalam daftar pilihan. Untuk melakukan ini, gunakan kelas System.Management.Automation.WildcardPattern untuk melakukan pencocokan pola karakter pengganti.

Berikut adalah implementasi default System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* dari file TemplateProvider.cs yang disediakan oleh Windows PowerShell.

Hal yang Perlu Diingat Tentang Menerapkan GetProperty

Kondisi berikut mungkin berlaku untuk implementasi System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*:

Saat menentukan kelas penyedia, penyedia properti Windows PowerShell mungkin mendeklarasikan kemampuan penyedia ExpandWildcards, Filter, Include, atau Exclude, dari enumerasi System.Management.Automation.Provider.ProviderCapabilities. Dalam kasus ini, implementasi metode System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* perlu memastikan bahwa jalur yang diteruskan ke metode memenuhi persyaratan kemampuan yang ditentukan. Untuk melakukan ini, metode harus mengakses properti yang sesuai, misalnya, properti System.Management.Automation.Provider.CmdletProvider.Exclude* dan System.Management.Automation.Provider.CmdletProvider.Include* .
Secara default, penggantian metode ini tidak boleh mengambil pembaca untuk objek yang disembunyikan dari pengguna kecuali properti System.Management.Automation.Provider.CmdletProvider.Force* diatur ke true. Kesalahan harus ditulis jika jalur mewakili item yang disembunyikan dari pengguna dan System.Management.Automation.Provider.CmdletProvider.Force* diatur ke false.

Melampirkan Parameter Dinamis ke Cmdlet Get-ItemProperty

Get-ItemProperty Cmdlet mungkin memerlukan parameter tambahan yang ditentukan secara dinamis pada runtime. Untuk menyediakan parameter dinamis ini, penyedia properti Windows PowerShell harus mengimplementasikan metode System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters*. Parameter menunjukkan path jalur internal penyedia yang memenuhi syarat penuh, sedangkan providerSpecificPickList parameter menentukan properti khusus penyedia yang dimasukkan pada baris perintah. Parameter ini mungkin atau null kosong jika properti disalurkan ke cmdlet. Dalam hal ini, metode ini mengembalikan objek yang memiliki properti dan bidang dengan atribut penguraian yang mirip dengan kelas cmdlet atau objek System.Management.Automation.RuntimeDefinedParameterDictionary . Runtime Windows PowerShell menggunakan objek yang dikembalikan untuk menambahkan parameter ke cmdlet.

Berikut adalah implementasi default System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* dari file TemplateProvider.cs yang disediakan oleh Windows PowerShell.

Mengatur Properti

Untuk mengatur properti, penyedia properti Windows PowerShell harus mengimplementasikan metode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* untuk mendukung panggilan dari Set-ItemProperty cmdlet. Metode ini mengatur satu atau beberapa properti item pada jalur yang ditentukan, dan menimpa properti yang disediakan sesuai kebutuhan. System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* juga menulis instans objek System.Management.Automation.PSObject yang mewakili kantong properti dari properti yang diperbarui.

Berikut adalah implementasi default System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* dari file TemplateProvider.cs yang disediakan oleh Windows PowerShell.

Hal-hal yang Perlu Diingat Tentang Menerapkan Set-ItemProperty

Kondisi berikut mungkin berlaku untuk implementasi System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*:

Saat menentukan kelas penyedia, penyedia properti Windows PowerShell mungkin mendeklarasikan kemampuan penyedia ExpandWildcards, Filter, Include, atau Exclude, dari enumerasi System.Management.Automation.Provider.ProviderCapabilities. Dalam kasus ini, implementasi metode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* harus memastikan bahwa jalur yang diteruskan ke metode memenuhi persyaratan kemampuan yang ditentukan. Untuk melakukan ini, metode harus mengakses properti yang sesuai, misalnya, properti System.Management.Automation.Provider.CmdletProvider.Exclude* dan System.Management.Automation.Provider.CmdletProvider.Include* .
Secara default, penggantian metode ini tidak boleh mengambil pembaca untuk objek yang disembunyikan dari pengguna kecuali properti System.Management.Automation.Provider.CmdletProvider.Force* diatur ke true. Kesalahan harus ditulis jika jalur mewakili item yang disembunyikan dari pengguna dan System.Management.Automation.Provider.CmdletProvider.Force* diatur ke false.
Implementasi Anda atas metode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* harus memanggil System.Management.Automation.Provider.CmdletProvider.ShouldProcess dan memverifikasi nilai yang dikembalikan sebelum membuat perubahan apa pun pada penyimpanan data. Metode ini digunakan untuk mengonfirmasi eksekusi operasi ketika perubahan dilakukan pada status sistem, misalnya, mengganti nama file. System.Management.Automation.Provider.CmdletProvider.ShouldProcess mengirimkan nama sumber daya yang akan diubah ke pengguna, dengan runtime Windows PowerShell dan menangani pengaturan baris perintah atau variabel preferensi dalam menentukan apa yang harus ditampilkan.

Setelah panggilan ke System.Management.Automation.Provider.CmdletProvider.ShouldProcess mengembalikan true, jika modifikasi sistem yang berpotensi berbahaya dapat dilakukan, metode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* harus memanggil metode System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Metode ini mengirimkan pesan konfirmasi ke pengguna untuk memungkinkan umpan balik tambahan untuk menunjukkan bahwa operasi harus dilanjutkan.

Melampirkan Parameter Dinamis untuk Cmdlet Set-ItemProperty

Set-ItemProperty Cmdlet mungkin memerlukan parameter tambahan yang ditentukan secara dinamis pada runtime. Untuk menyediakan parameter dinamis ini, penyedia properti Windows PowerShell harus mengimplementasikan metode System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters*. Metode ini mengembalikan objek yang memiliki properti dan bidang dengan atribut penguraian yang mirip dengan kelas cmdlet atau objek System.Management.Automation.RuntimeDefinedParameterDictionary . Nilai dapat null dikembalikan jika tidak ada parameter dinamis yang akan ditambahkan.

Berikut adalah implementasi default System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* dari file TemplateProvider.cs yang disediakan oleh Windows PowerShell.

Membersihkan Properti

Untuk menghapus properti, penyedia properti Windows PowerShell harus mengimplementasikan metode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* untuk mendukung panggilan dari Clear-ItemProperty cmdlet. Metode ini mengatur satu atau beberapa properti untuk item yang terletak di jalur yang ditentukan.

Berikut adalah implementasi default System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* dari file TemplateProvider.cs yang disediakan oleh Windows PowerShell.

Hal yang Perlu Diingat Tentang Menerapkan ClearProperty

Kondisi berikut mungkin berlaku untuk implementasi System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*:

Saat menentukan kelas penyedia, penyedia properti Windows PowerShell mungkin mendeklarasikan kemampuan penyedia ExpandWildcards, Filter, Include, atau Exclude, dari enumerasi System.Management.Automation.Provider.ProviderCapabilities. Dalam kasus ini, implementasi metode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* perlu memastikan bahwa jalur yang diteruskan ke metode memenuhi persyaratan kemampuan yang ditentukan. Untuk melakukan ini, metode harus mengakses properti yang sesuai, misalnya, properti System.Management.Automation.Provider.CmdletProvider.Exclude* dan System.Management.Automation.Provider.CmdletProvider.Include* .
Secara default, penggantian metode ini tidak boleh mengambil pembaca untuk objek yang disembunyikan dari pengguna kecuali properti System.Management.Automation.Provider.CmdletProvider.Force* diatur ke true. Kesalahan harus ditulis jika jalur mewakili item yang disembunyikan dari pengguna dan System.Management.Automation.Provider.CmdletProvider.Force* diatur ke false.
Implementasi metode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* harus memanggil System.Management.Automation.Provider.CmdletProvider.ShouldProcess dan memverifikasi nilai yang ditampilkan sebelum membuat perubahan apa pun pada penyimpanan data. Metode ini digunakan untuk mengonfirmasi eksekusi operasi sebelum perubahan dilakukan pada status sistem, seperti menghapus konten. System.Management.Automation.Provider.CmdletProvider.ShouldProcess mengirimkan nama sumber daya yang akan diubah ke pengguna, dengan runtime Windows PowerShell memperhitungkan pengaturan baris perintah atau variabel preferensi dalam menentukan apa yang harus ditampilkan.

Setelah panggilan ke System.Management.Automation.Provider.CmdletProvider.ShouldProcess mengembalikan true, jika modifikasi sistem yang berpotensi berbahaya dapat dilakukan, metode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* harus memanggil metode System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Metode ini mengirimkan pesan konfirmasi kepada pengguna untuk memungkinkan umpan balik tambahan yang menunjukkan bahwa operasi yang berpotensi berbahaya harus dilanjutkan.

Melampirkan Parameter Dinamis ke Cmdlet Clear-ItemProperty

Clear-ItemProperty Cmdlet mungkin memerlukan parameter tambahan yang ditentukan secara dinamis pada runtime. Untuk menyediakan parameter dinamis ini, penyedia properti Windows PowerShell harus mengimplementasikan metode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters*. Metode ini mengembalikan objek yang memiliki properti dan bidang dengan atribut penguraian yang mirip dengan kelas cmdlet atau objek System.Management.Automation.RuntimeDefinedParameterDictionary . Nilai dapat null dikembalikan jika tidak ada parameter dinamis yang akan ditambahkan.

Berikut adalah implementasi default System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* dari file TemplateProvider.cs yang disediakan oleh Windows PowerShell.