Tworzenie dostawcy właściwości Windows PowerShell

Ten temat opisuje, jak stworzyć dostawcę, który pozwala użytkownikowi manipulować właściwościami elementów w magazynie danych. W konsekwencji ten typ dostawcy nazywany jest dostawcą właściwości Windows PowerShell. Na przykład dostawca rejestru udostępniany przez Windows PowerShell obsługuje wartości kluczy 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 / Notatka

Windows PowerShell udostępnia plik szablonowy, który możesz wykorzystać do stworzenia dostawcy Windows PowerShell. Plik TemplateProvider.cs jest dostępny w Microsoft Windows Software Development Kit for Windows Vista oraz .NET Framework 3.0 Runtime Components. Instrukcje pobrania można znaleźć w sekcji Jak zainstalować Windows PowerShell oraz pobierz Windows PowerShell SDK. Pobrany szablon jest dostępny w katalogu <PowerShell Samples> . Powinieneś zrobić kopię tego pliku i użyć jej do utworzenia nowego dostawcy Windows PowerShell, usuwając wszelkie funkcje, których nie potrzebujesz. Więcej informacji o innych implementacjach dostawców Windows PowerShell można znaleźć w artykule Projektowanie swojego dostawcy Windows PowerShell.

Ostrzeżenie

Metody Twojego dostawcy nieruchomości powinny zapisywać obiekty za pomocą metody System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* .

Definiowanie dostawcy Windows PowerShell

Dostawca właściwości musi stworzyć klasę .NET wspierającą interfejs System.Management.Automation.Provider.IPropertyCmdletProvider . Oto domyślna deklaracja klas z pliku TemplateProvider.cs udostępnionego przez Windows PowerShell.

Definiowanie funkcjonalności bazowej

Interfejs System.Management.Automation.Provider.IPropertyCmdletProvider może być dołączony do dowolnej klasy bazowej dostawcy, z wyjątkiem klasy System.Management.Automation.Provider.DriveCmdletProvider . Dodaj podstawową funkcjonalność wymaganą przez klasę bazową, której używasz. Więcej informacji o klasach bazowych można znaleźć w artykule Projektowanie swojego dostawcy Windows PowerShell.

Pobieranie własności

Aby pobrać właściwości, dostawca musi zaimplementować metodę System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*, aby wspierać wywołania z cmdletu Get-ItemProperty . Ta metoda pobiera właściwości przedmiotu znajdującego się na określonej wewnętrznej ścieżce dostawcy (w pełni kwalifikowanej).

Parametr wskazuje, providerSpecificPickList które właściwości należy odzyskać. Jeśli ten parametr jest lub pusty null , metoda powinna pobrać wszystkie właściwości. Dodatkowo System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* zapisuje instancję obiektu System.Management.Automation.PSObject , który reprezentuje torbę z właściwościami pobranych właściwości. Metoda nie powinna nic zwracać.

Zaleca się, aby implementacja System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* wspierała rozszerzenie nazw właściwości dla każdego elementu z listy wyboru. Aby to zrobić, użyj klasy System.Management.Automation.WildcardPattern do wykonania dopasowania wzorców dzikich kart.

Oto domyślna implementacja System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* z pliku TemplateProvider.cs udostępnionego przez Windows PowerShell.

Rzeczy, o których warto pamiętać przy wdrażaniu GetProperty

Następujące warunki mogą mieć zastosowanie do Twojej implementacji System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*:

Podczas definiowania klasy dostawcy, dostawca właściwości Windows PowerShell może deklarować możliwości dostawcy takich jak ExpandWildcards, Filter, Include lub Exclude, z enumeracji System.Management.Automation.Provider.ProviderCapabilities . W takich przypadkach implementacja metody System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* musi zapewnić, że ścieżka przekazana metodzie spełnia wymagania określonych możliwości. Aby to zrobić, metoda powinna uzyskać dostęp do odpowiednich właściwości, na przykład do właściwości System.Management.Automation.Provider.CmdletProvider.Exclude* oraz System.Management.Automation.Provider.CmdletProvider.Include* .
Domyślnie nadpisania tej metody nie powinny pobierać czytnika obiektów ukrytych przed użytkownikiem, chyba że właściwość System.Management.Automation.Provider.CmdletProvider.Force* jest ustawiona na .true Błąd powinien zostać zapisany, jeśli ścieżka reprezentuje element ukryty przed użytkownikiem, a System.Management.Automation.Provider.CmdletProvider.Force* jest ustawione na false.

Przypisywanie parametrów dynamicznych do Get-ItemProperty Cmdlet

Cmdlet Get-ItemProperty może wymagać dodatkowych parametrów, które są określane dynamicznie w czasie działania. 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, natomiast parametr providerSpecificPickList określa właściwości specyficzne dla dostawcy wprowadzone w wierszu poleceń. Ten parametr może być lub pusty null , jeśli właściwości są przesyłane do cmdletu. W tym przypadku ta metoda zwraca obiekt posiadający właściwości i pola z atrybutami parsującymi podobnymi do klasy cmdlet lub obiektu System.Management.Automation.RuntimeDefinedParameterDictionary . Środowisko uruchomieniowe Windows PowerShell wykorzystuje zwrócony obiekt do dodawania parametrów do cmdletu.

Oto domyślna implementacja System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* z pliku TemplateProvider.cs udostępnionego 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 wspierać wywołania z cmdletu Set-ItemProperty . Ta metoda ustawia jedną lub więcej właściwości elementu na określonej ścieżce i nadpisuje dostarczone właściwości w razie potrzeby. System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* również zapisuje instancję obiektu System.Management.Automation.PSObject , który reprezentuje torbę z aktualnymi właściwościami.

Oto domyślna implementacja System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* z pliku TemplateProvider.cs udostępnionego przez Windows PowerShell.

Rzeczy, o których warto pamiętać przy wdrażaniu Set-ItemProperty

Następujące warunki mogą mieć zastosowanie do implementacji System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*:

Podczas definiowania klasy dostawcy, dostawca właściwości Windows PowerShell może deklarować możliwości dostawcy takich jak ExpandWildcards, Filter, Include lub Exclude, z enumeracji System.Management.Automation.Provider.ProviderCapabilities . W takich przypadkach implementacja metody System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* musi zapewnić, że ścieżka przekazana metodzie spełnia wymagania określonych możliwości. Aby to zrobić, metoda powinna uzyskać dostęp do odpowiednich właściwości, na przykład do właściwości System.Management.Automation.Provider.CmdletProvider.Exclude* oraz System.Management.Automation.Provider.CmdletProvider.Include* .
Domyślnie nadpisania tej metody nie powinny pobierać czytnika obiektów ukrytych przed użytkownikiem, chyba że właściwość System.Management.Automation.Provider.CmdletProvider.Force* jest ustawiona na .true Błąd powinien zostać zapisany, jeśli ścieżka reprezentuje element ukryty przed użytkownikiem, a System.Management.Automation.Provider.CmdletProvider.Force* jest ustawione na false.
Twoja implementacja metody System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* powinna wywołać System.Management.Automation.Provider.CmdletProvider.ShouldProcess i zweryfikować jej wartość zwrotną przed wprowadzeniem jakichkolwiek zmian w magazynie danych. Metoda ta służy do potwierdzenia wykonania operacji po zmianie stanu systemu, na przykład przy zmianie nazw plików. System.Management.Automation.Provider.CmdletProvider.ShouldProcess wysyła nazwę zasobu do zmiany użytkownikowi, wraz z runtime Windows PowerShell i obsługując ustawienia wiersza poleceń lub zmienne preferencyjne przy określaniu, co powinno być wyświetlane.

Po wywołaniu System.Management.Automation.Provider.CmdletProvider.ShouldProcess zwraca true, jeśli można wprowadzić potencjalnie niebezpieczne modyfikacje systemu, metoda System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* powinna wywołać metodę System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Ta metoda wysyła użytkownikowi wiadomość potwierdzającą, aby umożliwić dodatkowe informacje zwrotne wskazujące, że operacja powinna być kontynuowana.

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

Cmdlet Set-ItemProperty może wymagać dodatkowych parametrów, które są określane dynamicznie w czasie działania. 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 posiadający właściwości i pola z atrybutami parsowania podobnymi do klasy cmdlet lub obiektu System.Management.Automation.RuntimeDefinedParameterDictionary . Wartość może zostać zwrócona, null jeśli nie dodaje się żadnych parametrów dynamicznych.

Oto domyślna implementacja System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* z pliku TemplateProvider.cs udostępnionego przez Windows PowerShell.

Właściwości rozliczania

Aby usunąć właściwości, dostawca właściwości Windows PowerShell musi zaimplementować metodę System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*, aby wspierać wywołania z cmdletu Clear-ItemProperty . Ta metoda ustawia jedną lub więcej właściwości dla elementu znajdującego się na określonej ścieżce.

Oto domyślna implementacja System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* z pliku TemplateProvider.cs udostępnionego przez Windows PowerShell.

Warto pamiętać o implementacji ClearProperty

Następujące warunki mogą mieć zastosowanie do Twojej implementacji System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*:

Podczas definiowania klasy dostawcy, dostawca właściwości Windows PowerShell może deklarować możliwości dostawcy takich jak ExpandWildcards, Filter, Include lub Exclude, z enumeracji System.Management.Automation.Provider.ProviderCapabilities . W takich przypadkach implementacja metody System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* musi zapewnić, że ścieżka przekazana metodzie spełnia wymagania określonych możliwości. Aby to zrobić, metoda powinna uzyskać dostęp do odpowiednich właściwości, na przykład do właściwości System.Management.Automation.Provider.CmdletProvider.Exclude* oraz System.Management.Automation.Provider.CmdletProvider.Include* .
Domyślnie nadpisania tej metody nie powinny pobierać czytnika obiektów ukrytych przed użytkownikiem, chyba że właściwość System.Management.Automation.Provider.CmdletProvider.Force* jest ustawiona na .true Błąd powinien zostać zapisany, jeśli ścieżka reprezentuje element ukryty przed użytkownikiem, a System.Management.Automation.Provider.CmdletProvider.Force* jest ustawione na false.
Twoja implementacja metody System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* powinna wywołać System.Management.Automation.Provider.CmdletProvider.ShouldProcess i zweryfikować jej wartość zwrotną przed wprowadzeniem jakichkolwiek zmian w magazynie danych. Metoda ta służy do potwierdzenia wykonania operacji przed wprowadzeniem zmiany stanu systemu, takiej jak wyczyszczenie zawartości. System.Management.Automation.Provider.CmdletProvider.ShouldProcess wysyła nazwę zasobu do zmiany do użytkownika, przy czym środowisko działania Windows PowerShell uwzględnia wszelkie ustawienia wiersza poleceń lub zmienne preferencyjne przy określaniu, co powinno być wyświetlane.

Po wywołaniu do System.Management.Automation.Provider.CmdletProvider.ShouldProcess zwraca true, jeśli można wprowadzić potencjalnie niebezpieczne modyfikacje systemu, metoda System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* powinna wywołać metodę System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Ta metoda wysyła użytkownikowi komunikat potwierdzający, aby umożliwić dodatkowe informacje zwrotne wskazujące, że potencjalnie niebezpieczna operacja powinna zostać kontynuowana.

Przypisywanie parametrów dynamicznych do Clear-ItemProperty Cmdlet

Cmdlet Clear-ItemProperty może wymagać dodatkowych parametrów, które są określane dynamicznie w czasie działania. 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 posiadający właściwości i pola z atrybutami parsowania podobnymi do klasy cmdlet lub obiektu System.Management.Automation.RuntimeDefinedParameterDictionary . Wartość może zostać zwrócona, null jeśli nie dodaje się żadnych parametrów dynamicznych.

Oto domyślna implementacja System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* z pliku TemplateProvider.cs udostępnionego przez Windows PowerShell.