Erstellung eines Windows PowerShell Property Provider

Dieses Thema beschreibt, wie man einen Anbieter erstellt, der es dem Benutzer ermöglicht, die Eigenschaften von Elementen in einem Datenspeicher zu manipulieren. Folglich wird dieser Anbietertyp als Windows PowerShell Property Provider bezeichnet. Beispielsweise behandelt der von Windows PowerShell bereitgestellte Registry-Provider die Registrierungsschlüsselwerte als Eigenschaften des Registrierungsschlüsselelements. Dieser Anbietertyp muss die System.Management.Automation.Provider.IPropertyCmdletProvider-Schnittstelle zur Implementierung der .NET-Klasse hinzufügen.

Hinweis

Windows PowerShell bietet eine Vorlagendatei, die Sie verwenden können, um einen Windows-PowerShell-Anbieter zu entwickeln. Die TemplateProvider.cs-Datei ist im Microsoft Windows Software Development Kit für Windows Vista und .NET Framework 3.0 Runtime Components verfügbar. Für Download-Anweisungen siehe Wie man Windows PowerShell installiert und das Windows PowerShell SDK herunterlädt. Die heruntergeladene Vorlage ist im <PowerShell Samples-Verzeichnis> verfügbar. Du solltest eine Kopie dieser Datei anfertigen und die Kopie nutzen, um einen neuen Windows-PowerShell-Anbieter zu erstellen, wobei du alle Funktionen entfernst, die du nicht brauchst. Weitere Informationen zu anderen Implementierungen von Windows PowerShell-Anbietern finden Sie unter Designing Your Windows PowerShell Provider.

Vorsicht

Die Methoden Ihres Property Providers sollten alle Objekte mit der Methode System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* schreiben.

Definition des Windows-PowerShell-Anbieters

Ein Property Provider muss eine .NET-Klasse erstellen, die die System.Management.Automation.Provider.IPropertyCmdletProvider-Schnittstelle unterstützt. Hier ist die Standard-Klassendeklaration aus der TemplateProvider.cs-Datei, die von Windows PowerShell bereitgestellt wird.

Definition der Basisfunktionalität

Die System.Management.Automation.Provider.IPropertyCmdletProvider-Schnittstelle kann an jede der Anbieter-Basisklassen angeschlossen werden, mit Ausnahme der System.Management.Automation.Provider.DriveCmdletProvider-Klasse . Füge die Basisfunktionalität hinzu, die von der von dir verwendeten Basisklasse benötigt wird. Weitere Informationen zu Basisklassen finden Sie unter Designing Your Windows PowerShell Provider.

Abruf von Eigenschaften

Um Eigenschaften abzurufen, muss der Anbieter die Methode System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* implementieren, um Aufrufe vom Cmdlet Get-ItemProperty zu unterstützen. Diese Methode ruft die Eigenschaften des Objekts ab, das sich am angegebenen provider-internen Pfad befindet (vollständig qualifiziert).

Der Parameter providerSpecificPickList gibt an, welche Eigenschaften abgerufen werden sollen. Ist dieser Parameter null oder leer, sollte die Methode alle Eigenschaften abrufen. Zusätzlich schreibt System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* eine Instanz eines System.Management.Automation.PSObject-Objekts , das eine Property Bag der abgerufenen Eigenschaften darstellt. Die Methode sollte nichts zurückbringen.

Es wird empfohlen, dass die Implementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* die Jokererweiterung der Eigenschaftsnamen für jedes Element in der Auswahlliste unterstützt. Dazu verwenden Sie die Klasse System.Management.Automation.WildcardPattern , um das Wildcard-Mustermatching durchzuführen.

Hier ist die Standardimplementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* aus der von Windows PowerShell bereitgestellten TemplateProvider.cs-Datei.

Was Sie bei der Implementierung von GetProperty beachten sollten

Die folgenden Bedingungen können für Ihre Implementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* gelten:

Bei der Definition der Provider-Klasse kann ein Windows-PowerShell-Property-Anbieter die Providerfähigkeiten ExpandWildcards, Filter, Include oder Exclude aus der System.Management.Automation.Provider.ProviderProvider-Enumeration deklarieren. In diesen Fällen muss die Implementierung der System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* -Methode sicherstellen, dass der an die Methode weitergegebene Pfad die Anforderungen der angegebenen Fähigkeiten erfüllt. Dazu sollte die Methode auf die entsprechenden Eigenschaften zugreifen, zum Beispiel System.Management.Automation.Provider.CmdletProvider.Exclude* und System.Management.Automation.Provider.CmdletProvider.Include* -Eigenschaften.
Standardmäßig sollten Überschreibungen dieser Methode keinen Leser für Objekte abrufen, die für den Benutzer verborgen sind, es sei denn, die Eigenschaft System.Management.Automation.Provider.CmdletProvider.Force* ist auf truegesetzt. Ein Fehler sollte geschrieben werden, wenn der Pfad ein vom Benutzer verborgenes Element repräsentiert und System.Management.Automation.Provider.CmdletProvider.Force* auf falsegesetzt ist.

Dynamische Parameter an das Get-ItemProperty Cmdlet anhängen

Das Get-ItemProperty Cmdlet kann zusätzliche Parameter benötigen, die zur Laufzeit dynamisch festgelegt werden. Um diese dynamischen Parameter bereitzustellen, muss der Windows-PowerShell-Property-Anbieter die Methode System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* implementieren. Der Parameter path gibt einen vollständig qualifizierten provider-internen Pfad an, während der Parameter providerSpecificPickList die providerspezifischen Eigenschaften angibt, die in der Kommandozeile eingegeben werden. Dieser Parameter kann leer sein null , wenn die Eigenschaften an das Cmdlet gepipt werden. In diesem Fall gibt diese Methode ein Objekt zurück, das Eigenschaften und Felder mit Parsing-Attributen besitzt, ähnlich wie eine cmdlet-Klasse oder ein System.Management.Automation.RuntimeDefinedParameterDictionary-Objekt . Die Windows-PowerShell-Laufzeit verwendet das zurückgegebene Objekt, um die Parameter zum Cmdlet hinzuzufügen.

Hier ist die Standardimplementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* aus der TemplateProvider.cs-Datei, die von Windows PowerShell bereitgestellt wird.

Festlegen von Eigenschaften

Um Eigenschaften festzulegen, muss der Windows-PowerShell-Property-Anbieter die Methode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* implementieren, um Aufrufe vom Cmdlet Set-ItemProperty zu unterstützen. Diese Methode setzt eine oder mehrere Eigenschaften des Objekts auf dem angegebenen Pfad und überschreibt die bereitgestellten Eigenschaften bei Bedarf überschrieben. System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* schreibt außerdem eine Instanz eines System.Management.Automation.PSObject-Objekts , das eine Property Bag der aktualisierten Eigenschaften darstellt.

Hier ist die Standardimplementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* aus der von Windows PowerShell bereitgestellten TemplateProvider.cs-Datei.

Was sollten Sie bei der Umsetzung Set-ItemProperty

Die folgenden Bedingungen können für eine Implementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* gelten:

Bei der Definition der Provider-Klasse kann ein Windows-PowerShell-Property-Anbieter die Providerfähigkeiten ExpandWildcards, Filter, Include oder Exclude aus der System.Management.Automation.Provider.ProviderProvider-Enumeration deklarieren. In diesen Fällen muss die Implementierung der System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* -Methode sicherstellen, dass der an die Methode weitergegebene Pfad die Anforderungen der spezifizierten Fähigkeiten erfüllt. Dazu sollte die Methode auf die entsprechenden Eigenschaften zugreifen, zum Beispiel System.Management.Automation.Provider.CmdletProvider.Exclude* und System.Management.Automation.Provider.CmdletProvider.Include* -Eigenschaften.
Standardmäßig sollten Überschreibungen dieser Methode keinen Leser für Objekte abrufen, die für den Benutzer verborgen sind, es sei denn, die Eigenschaft System.Management.Automation.Provider.CmdletProvider.Force* ist auf truegesetzt. Ein Fehler sollte geschrieben werden, wenn der Pfad ein vom Benutzer verborgenes Element repräsentiert und System.Management.Automation.Provider.CmdletProvider.Force* auf falsegesetzt ist.
Ihre Implementierung der System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*- Methode sollte System.Management.Automation.Provider.CmdletProvider.ShouldProcess aufrufen und den Rückgabewert überprüfen, bevor sie Änderungen am Datenspeicher vornimmt. Diese Methode wird verwendet, um die Ausführung einer Operation zu bestätigen, wenn eine Änderung des Systemzustands vorgenommen wird, zum Beispiel durch das Umbenennen von Dateien. System.Management.Automation.Provider.CmdletProvider.ShouldProcess sendet den Namen der zu ändernden Ressource an den Benutzer, zusammen mit der Windows-PowerShell-Laufzeit und übernimmt alle Kommandozeileneinstellungen oder Präferenzvariablen bei der Entscheidung, was angezeigt werden soll.

Nachdem der Aufruf von System.Management.Automation.Provider.CmdletProvider.ShouldProcess zurückgekehrt trueist, sollte die System.Management.Automation.Automation.Provider.IPropertyCmdletProvider.SetProperty* -Methode die Methode System.Management.Automation.Automation.Provider.CmdletProvider.ShouldContinue aufrufen. Diese Methode sendet eine Bestätigungsnachricht an den Benutzer, um zusätzliches Feedback zu erhalten, das anzeigt, dass der Vorgang fortgesetzt werden soll.

Dynamische Parameter für das Set-ItemProperty Cmdlet anhängen

Das Set-ItemProperty Cmdlet kann zusätzliche Parameter benötigen, die zur Laufzeit dynamisch festgelegt werden. Um diese dynamischen Parameter bereitzustellen, muss der Windows-PowerShell-Property-Anbieter die Methode System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* implementieren. Diese Methode gibt ein Objekt zurück, das Eigenschaften und Felder mit Parsing-Attributen besitzt, ähnlich einer cmdlet-Klasse oder einem System.Management.Automation.RuntimeDefinedParameterDictionary-Objekt . Der Wert null kann zurückgegeben werden, wenn keine dynamischen Parameter hinzugefügt werden sollen.

Räumungseigenschaften

Um Eigenschaften zu löschen, muss der Windows-PowerShell-Property-Anbieter die Methode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* implementieren, um Aufrufe vom Cmdlet Clear-ItemProperty zu unterstützen. Diese Methode legt eine oder mehrere Eigenschaften für das am angegebenen Pfad liegende Objekt fest.

Hier ist die Standardimplementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* aus der von Windows PowerShell bereitgestellten TemplateProvider.cs-Datei.

Was Sie bei der Implementierung von ClearProperty beachten sollten

Die folgenden Bedingungen können für Ihre Implementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* gelten:

Bei der Definition der Provider-Klasse kann ein Windows-PowerShell-Property-Anbieter die Providerfähigkeiten ExpandWildcards, Filter, Include oder Exclude aus der System.Management.Automation.Provider.ProviderProvider-Enumeration deklarieren. In diesen Fällen muss die Implementierung der System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* -Methode sicherstellen, dass der an die Methode weitergegebene Pfad die Anforderungen der angegebenen Fähigkeiten erfüllt. Dazu sollte die Methode auf die entsprechenden Eigenschaften zugreifen, zum Beispiel System.Management.Automation.Provider.CmdletProvider.Exclude* und System.Management.Automation.Provider.CmdletProvider.Include* -Eigenschaften.
Standardmäßig sollten Überschreibungen dieser Methode keinen Leser für Objekte abrufen, die für den Benutzer verborgen sind, es sei denn, die Eigenschaft System.Management.Automation.Provider.CmdletProvider.Force* ist auf truegesetzt. Ein Fehler sollte geschrieben werden, wenn der Pfad ein vom Benutzer verborgenes Element repräsentiert und System.Management.Automation.Provider.CmdletProvider.Force* auf falsegesetzt ist.
Ihre Implementierung der System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*- Methode sollte System.Management.Automation.Provider.CmdletProvider.ShouldProcess aufrufen und deren Rückgabewert überprüfen, bevor Änderungen am Datenspeicher vorgenommen werden. Diese Methode wird verwendet, um die Ausführung einer Operation zu bestätigen, bevor eine Änderung des Systemzustands vorgenommen wird, wie zum Beispiel das Löschen von Inhalten. System.Management.Automation.Provider.CmdletProvider.ShouldProcess sendet den Namen der zu ändernden Ressource an den Benutzer, wobei die Windows-PowerShell-Laufzeit alle Kommandozeileneinstellungen oder Präferenzvariablen berücksichtigt, um zu bestimmen, was angezeigt werden soll.

Nachdem der Aufruf von System.Management.Automation.Provider.CmdletProvider.ShouldProcess zurückkehrt true, sollte System.Management.Automation.Automation.Provider.IPropertyCmdletProvider.ClearProperty* die Methode System.Management.Automation.Automation.Provider.CmdletProvider.ShouldContinue aufrufen. Diese Methode sendet eine Bestätigungsnachricht an den Benutzer, um zusätzliches Feedback zu erhalten, das darauf hinweist, dass der potenziell gefährliche Vorgang fortgesetzt werden sollte.

Dynamische Parameter an das Clear-ItemProperty Cmdlet anhängen

Das Clear-ItemProperty Cmdlet kann zusätzliche Parameter benötigen, die zur Laufzeit dynamisch festgelegt werden. Um diese dynamischen Parameter bereitzustellen, muss der Windows-PowerShell-Property-Anbieter die Methode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* implementieren. Diese Methode gibt ein Objekt zurück, das Eigenschaften und Felder mit Parsing-Attributen besitzt, ähnlich einer cmdlet-Klasse oder einem System.Management.Automation.RuntimeDefinedParameterDictionary-Objekt . Der Wert null kann zurückgegeben werden, wenn keine dynamischen Parameter hinzugefügt werden sollen.

Hier ist die Standardimplementierung von System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* aus der von Windows PowerShell bereitgestellten TemplateProvider.cs-Datei.