Tworzenie dostawcy właściwości programu Windows PowerShell

Artykuł
09/27/2021

W tym temacie opisano sposób tworzenia dostawcy, który umożliwia użytkownikowi manipulowanie właściwościami elementów w magazynie danych. W związku z tym ten typ dostawcy jest określany jako dostawca Windows PowerShell właściwości. Na przykład dostawca rejestru dostarczony przez Windows PowerShell obsługuje wartości klucza rejestru jako właściwości elementu klucza rejestru. Ten typ dostawcy musi dodać interfejs System.Management.Automation.Provider.Ipropertycmdletprovider do implementacji klasy .NET.

Uwaga

Windows PowerShell udostępnia plik szablonu, za pomocą Windows PowerShell dostawcy. Plik TemplateProvider.cs jest dostępny w zestawie Microsoft Windows Software Development Kit dla systemów Windows Vista i .NET Framework 3.0 Runtime Components. Aby uzyskać instrukcje dotyczące pobierania, zobacz How to Install Windows PowerShell and Download the Windows PowerShell SDK (Jak zainstalować zestaw SDK Windows PowerShell). Pobrany szablon jest dostępny w <PowerShell Samples> katalogu . Należy utworzyć kopię tego pliku i użyć jej do utworzenia nowego dostawcy Windows PowerShell, usuwając wszelkie potrzebne funkcje. Aby uzyskać więcej informacji na temat Windows PowerShell implementacji innych dostawców, zobacz Designing Your Windows PowerShell Provider.

Przestroga

Metody dostawcy właściwości powinny zapisywać wszystkie obiekty przy użyciu metody System.Management.Automation.Provider.Cmdletprovider.Writepropertyobject*.

Definiowanie dostawcy Windows PowerShell danych

Dostawca właściwości musi utworzyć klasę .NET, która obsługuje interfejs System.Management.Automation.Provider.Ipropertycmdletprovider. Oto domyślna deklaracja klasy z pliku TemplateProvider.cs dostarczonego przez Windows PowerShell.

Definiowanie podstawowych funkcji

Interfejs System.Management.Automation.Provider.Ipropertycmdletprovider można dołączyć do dowolnej klasy bazowej dostawcy, z wyjątkiem klasy System.Management.Automation.Provider.Drivecmdletprovider. Dodaj podstawowe funkcje wymagane przez używaną klasę bazową. Aby uzyskać więcej informacji na temat klas bazowych, zobacz Designing Your Windows PowerShell Provider (Projektowanie dostawcy Windows PowerShell danych).

Pobieranie właściwości

Aby pobrać właściwości, dostawca musi zaimplementować metodę System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty*, aby obsługiwać wywołania z Get-ItemProperty polecenia cmdlet . Ta metoda pobiera właściwości elementu znajdującego się w określonej ścieżce wewnętrznej dostawcy (w pełni kwalifikowana).

Parametr providerSpecificPickList wskazuje właściwości do pobrania. Jeśli ten parametr jest null pusty lub jest pusty, metoda powinna pobrać wszystkie właściwości. Ponadto System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* zapisuje wystąpienie obiektu System.Management.Automation.PSObject, które reprezentuje torbę właściwości pobranych właściwości. Metoda nie powinna zwracać żadnych danych.

Zaleca się, aby implementacja elementu System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* obsługuje rozszerzenie nazw właściwości dla każdego elementu na liście wyboru z symbolami wieloznacznych. Aby to zrobić, użyj klasy System.Management.Automation.Wildcardpattern, aby dopasować wzorzec z symbolami wieloznacznymi.

Oto domyślna implementacja pliku System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* z pliku TemplateProvider.cs dostarczonego przez Windows PowerShell.

Co należy pamiętać o implementowanie GetProperty

Następujące warunki mogą dotyczyć implementacji właściwości System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty*:

Podczas definiowania klasy dostawcy dostawca właściwości Windows PowerShell może deklarować możliwości dostawcy expandWildcards, Filter, Include lub Exclude z wyliczenia System.Management.Automation.Provider.Providercapabilities. W takich przypadkach implementacja metody System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* musi zapewnić, że ścieżka przekazana do metody spełnia wymagania określonych możliwości. W tym celu metoda powinna uzyskać dostęp do odpowiedniej właściwości, na przykład właściwości System.Management.Automation.Provider.Cmdletprovider.Exclude* i System.Management.Automation.Provider.Cmdletprovider.Include*.
Domyślnie przesłonięcia tej metody nie powinny pobierać czytnika obiektów, które są ukryte przed użytkownikiem, chyba że właściwość System.Management.Automation.Provider.Cmdletprovider.Force* jest ustawiona na true wartość . Jeśli ścieżka reprezentuje element ukryty przed użytkownikiem, a element System.Management.Automation.Provider.Cmdletprovider.Force* jest ustawiony na false wartość .

Dołączanie parametrów dynamicznych do Get-ItemProperty cmdlet

Polecenie Get-ItemProperty cmdlet może wymagać dodatkowych parametrów, które są określane dynamicznie w czasie wykonywania. Aby zapewnić te parametry dynamiczne, dostawca właściwości Windows PowerShell musi zaimplementować metodę System.Management.Automation.Provider.Ipropertycmdletprovider.Getpropertydynamicparameters*. Parametr path wskazuje w pełni kwalifikowaną ścieżkę wewnętrzną dostawcy, a parametr określa właściwości specyficzne dla dostawcy wprowadzone w providerSpecificPickList wierszu polecenia. Ten parametr może być null lub pusty, jeśli właściwości są potokowe do polecenia cmdlet. W tym przypadku ta metoda zwraca obiekt, który ma właściwości i pola z atrybutami analizowania podobnymi do klasy polecenia cmdlet lub obiektu System.Management.Automation.Runtimedefinedparameterdictionary. Środowisko Windows PowerShell używa zwróconego obiektu w celu dodania parametrów do polecenia cmdlet .

Oto domyślna implementacja pliku System.Management.Automation.Provider.Ipropertycmdletprovider.Getpropertydynamicparameters* z pliku TemplateProvider.cs dostarczonego przez Windows PowerShell.

Ustawianie właściwości

Aby ustawić właściwości, dostawca właściwości Windows PowerShell musi zaimplementować metodę System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty*, aby obsługiwać wywołania z Set-ItemProperty polecenia cmdlet . Ta metoda ustawia co najmniej jedną właściwości elementu w określonej ścieżce i zastępuje podane właściwości zgodnie z potrzebami. System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* zapisuje również wystąpienie obiektu System.Management.Automation.PSObject, które reprezentuje zbiór właściwości zaktualizowanych właściwości.

Oto domyślna implementacja pliku System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* z pliku TemplateProvider.cs dostarczonego przez Windows PowerShell.

Co należy zapamiętać na temat implementowania Set-ItemProperty

Następujące warunki mogą dotyczyć implementacji właściwości System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty*:

Podczas definiowania klasy dostawcy dostawca właściwości Windows PowerShell może deklarować możliwości dostawcy expandWildcards, Filter, Include lub Exclude z wyliczenia System.Management.Automation.Provider.Providercapabilities. W takich przypadkach implementacja metody System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* musi zapewnić, że ścieżka przekazana do metody spełnia wymagania określonych możliwości. W tym celu metoda powinna uzyskać dostęp do odpowiedniej właściwości, na przykład właściwości System.Management.Automation.Provider.Cmdletprovider.Exclude* i System.Management.Automation.Provider.Cmdletprovider.Include*.
Domyślnie przesłonięcia tej metody nie powinny pobierać czytnika obiektów, które są ukryte przed użytkownikiem, chyba że właściwość System.Management.Automation.Provider.Cmdletprovider.Force* jest ustawiona na true wartość . Jeśli ścieżka reprezentuje element ukryty przed użytkownikiem, a element System.Management.Automation.Provider.Cmdletprovider.Force* jest ustawiony na false wartość .
Implementacja metody System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* powinna wywołać metodę System.Management.Automation.Provider.Cmdletprovider.ShouldProcess i sprawdzić jej wartość zwracaną przed wprowadzeniem jakichkolwiek zmian w magazynie danych. Ta metoda służy do potwierdzania wykonania operacji w przypadku zmiany stanu systemu, na przykład zmiany nazw plików. System.Management.Automation.Provider.Cmdletprovider.ShouldProcess wysyła nazwę zasobu, który ma zostać zmieniony do użytkownika, ze środowiskiem uruchomieniowym programu Windows PowerShell i obsługą wszelkich ustawień wiersza polecenia lub zmiennych preferencji podczas określania, co powinno być wyświetlane.

Po wywołaniu metody System.Management.Automation.Provider.Cmdletprovider.ShouldProcess zwraca wartość , jeśli mogą zostać wprowadzone potencjalnie niebezpieczne modyfikacje systemu, metoda true System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* powinna wywołać metodę System.Management.Automation.Provider.Cmdletprovider.ShouldContinue. Ta metoda wysyła do użytkownika komunikat potwierdzający, aby zezwolić na dodatkową opinię w celu wskazania, że operacja powinna być kontynuowana.

Dołączanie parametrów dynamicznych dla Set-ItemProperty cmdlet

Polecenie Set-ItemProperty cmdlet może wymagać dodatkowych parametrów, które są określane dynamicznie w czasie wykonywania. Aby zapewnić te parametry dynamiczne, dostawca właściwości Windows PowerShell musi zaimplementować metodę System.Management.Automation.Provider.Ipropertycmdletprovider.Setpropertydynamicparameters*. Ta metoda zwraca obiekt, który ma właściwości i pola z atrybutami analizowania podobnymi do klasy polecenia cmdlet lub obiektu System.Management.Automation.Runtimedefinedparameterdictionary. Wartość null może być zwracana, jeśli nie mają zostać dodane żadne parametry dynamiczne.

Oto domyślna implementacja pliku System.Management.Automation.Provider.Ipropertycmdletprovider.Getpropertydynamicparameters* z pliku TemplateProvider.cs dostarczonego przez Windows PowerShell.

Czyszczenie właściwości

Aby wyczyścić właściwości, dostawca właściwości Windows PowerShell musi zaimplementować metodę System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty*, aby obsługiwać wywołania z Clear-ItemProperty polecenia cmdlet . Ta metoda ustawia co najmniej jedną właściwości dla elementu znajdującego się w określonej ścieżce.

Oto domyślna implementacja pliku System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* z pliku TemplateProvider.cs dostarczonego przez Windows PowerShell.

Thing to Remember About Implementing ClearProperty

Następujące warunki mogą dotyczyć implementacji właściwości System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty*:

Podczas definiowania klasy dostawcy dostawca właściwości Windows PowerShell może deklarować możliwości dostawcy expandWildcards, Filter, Include lub Exclude z wyliczenia System.Management.Automation.Provider.Providercapabilities. W takich przypadkach implementacja metody System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* musi zapewnić, że ścieżka przekazana do metody spełnia wymagania określonych możliwości. W tym celu metoda powinna uzyskać dostęp do odpowiedniej właściwości, na przykład właściwości System.Management.Automation.Provider.Cmdletprovider.Exclude* i System.Management.Automation.Provider.Cmdletprovider.Include*.
Domyślnie przesłonięcia tej metody nie powinny pobierać czytnika obiektów, które są ukryte przed użytkownikiem, chyba że właściwość System.Management.Automation.Provider.Cmdletprovider.Force* jest ustawiona na true wartość . Jeśli ścieżka reprezentuje element ukryty przed użytkownikiem, a element System.Management.Automation.Provider.Cmdletprovider.Force* jest ustawiony na false wartość .
Implementacja metody System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* powinna wywołać metodę System.Management.Automation.Provider.Cmdletprovider.ShouldProcess i sprawdzić jej wartość zwracaną przed wprowadzeniem jakichkolwiek zmian w magazynie danych. Ta metoda służy do potwierdzania wykonania operacji przed zmianą stanu systemu, taką jak czyszczenie zawartości. System.Management.Automation.Provider.Cmdletprovider.ShouldProcess wysyła nazwę zasobu, który ma zostać zmieniony, do użytkownika, przy czym środowisko uruchomieniowe programu Windows PowerShell uwzględnia wszystkie ustawienia wiersza polecenia lub zmienne preferencji podczas określania, co powinno być wyświetlane.

Po wywołaniu metody System.Management.Automation.Provider.Cmdletprovider.ShouldProcess zwraca wartość , jeśli mogą zostać wprowadzone potencjalnie niebezpieczne modyfikacje systemu, metoda true System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* powinna wywołać metodę System.Management.Automation.Provider.Cmdletprovider.ShouldContinue. Ta metoda wysyła do użytkownika komunikat potwierdzający, aby zezwolić na dodatkowe informacje zwrotne wskazujące, że potencjalnie niebezpieczna operacja powinna być kontynuowana.

Dołączanie parametrów dynamicznych do Clear-ItemProperty cmdlet

Polecenie Clear-ItemProperty cmdlet może wymagać dodatkowych parametrów, które są określane dynamicznie w czasie wykonywania. Aby zapewnić te parametry dynamiczne, dostawca właściwości Windows PowerShell musi zaimplementować metodę System.Management.Automation.Provider.Ipropertycmdletprovider.Clearpropertydynamicparameters*. Ta metoda zwraca obiekt, który ma właściwości i pola z atrybutami analizowania podobnymi do klasy polecenia cmdlet lub obiektu System.Management.Automation.Runtimedefinedparameterdictionary. Wartość null może być zwracana, jeśli nie mają zostać dodane żadne parametry dynamiczne.

Oto domyślna implementacja pliku System.Management.Automation.Provider.Ipropertycmdletprovider.Clearpropertydynamicparameters* z pliku TemplateProvider.cs dostarczonego przez Windows PowerShell.