Creating a Windows PowerShell Property Provider

Artículo
09/17/2021

This topic describes how to create a provider that enables the user to manipulate the properties of items in a data store. As a consequence, this type of provider is referred to as a Windows PowerShell property provider. For example, the Registry provider provided by Windows PowerShell handles registry key values as properties of the registry key item. This type of provider must add the System.Management.Automation.Provider.Ipropertycmdletprovider interface to the implementation of the .NET class.

Note

Windows PowerShell provides a template file that you can use to develop a Windows PowerShell provider. The TemplateProvider.cs file is available on the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see How to Install Windows PowerShell and Download the Windows PowerShell SDK. The downloaded template is available in the <PowerShell Samples> directory. You should make a copy of this file and use the copy for creating a new Windows PowerShell provider, removing any functionality that you do not need. For more information about other Windows PowerShell provider implementations, see Designing Your Windows PowerShell Provider.

Caution

The methods of your property provider should write any objects using the System.Management.Automation.Provider.Cmdletprovider.Writepropertyobject* method.

Defining the Windows PowerShell provider

A property provider must create a .NET class that supports the System.Management.Automation.Provider.Ipropertycmdletprovider interface. Here is the default class declaration from the TemplateProvider.cs file provided by Windows PowerShell.

Defining Base Functionality

The System.Management.Automation.Provider.Ipropertycmdletprovider interface can be attached to any of the provider base classes, with the exception of the System.Management.Automation.Provider.Drivecmdletprovider class. Add the base functionality that is required by the base class you are using. For more information about base classes, see Designing Your Windows PowerShell Provider.

Retrieving Properties

To retrieve properties, the provider must implement the System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* method to support calls from the Get-ItemProperty cmdlet. This method retrieves the properties of the item located at the specified provider-internal path (fully-qualified).

The providerSpecificPickList parameter indicates which properties to retrieve. If this parameter is null or empty, the method should retrieve all properties. In addition, System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* writes an instance of a System.Management.Automation.PSObject object that represents a property bag of the retrieved properties. The method should return nothing.

It is recommended that the implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* supports the wildcard expansion of property names for each element in the pick list. To do this, use the System.Management.Automation.Wildcardpattern class to perform the wildcard pattern matching.

Here is the default implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* from the TemplateProvider.cs file provided by Windows PowerShell.

Things to Remember About Implementing GetProperty

The following conditions may apply to your implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty*:

When defining the provider class, a Windows PowerShell property provider might declare provider capabilities of ExpandWildcards, Filter, Include, or Exclude, from the System.Management.Automation.Provider.Providercapabilities enumeration. In these cases, the implementation of the System.Management.Automation.Provider.Ipropertycmdletprovider.Getproperty* method needs to ensure that the path passed to the method meets the requirements of the specified capabilities. To do this, the method should access the appropriate property, for example, the System.Management.Automation.Provider.Cmdletprovider.Exclude* and System.Management.Automation.Provider.Cmdletprovider.Include* properties.
By default, overrides of this method should not retrieve a reader for objects that are hidden from the user unless the System.Management.Automation.Provider.Cmdletprovider.Force* property is set to true. An error should be written if the path represents an item that is hidden from the user and System.Management.Automation.Provider.Cmdletprovider.Force* is set to false.

Attaching Dynamic Parameters to the Get-ItemProperty Cmdlet

The Get-ItemProperty cmdlet might require additional parameters that are specified dynamically at runtime. To provide these dynamic parameters, the Windows PowerShell property provider must implement the System.Management.Automation.Provider.Ipropertycmdletprovider.Getpropertydynamicparameters* method. The path parameter indicates a fully-qualified provider-internal path, while the providerSpecificPickList parameter specifies the provider-specific properties entered on the command line. This parameter might be null or empty if the properties are piped to the cmdlet. In this case, this method returns an object that has properties and fields with parsing attributes similar to a cmdlet class or a System.Management.Automation.Runtimedefinedparameterdictionary object. The Windows PowerShell runtime uses the returned object to add the parameters to the cmdlet.

Here is the default implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Getpropertydynamicparameters* from the TemplateProvider.cs file provided by Windows PowerShell.

Setting Properties

To set properties, the Windows PowerShell property provider must implement the System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* method to support calls from the Set-ItemProperty cmdlet. This method sets one or more properties of the item at the specified path, and overwrites the supplied properties as required. System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* also writes an instance of a System.Management.Automation.PSObject object that represents a property bag of the updated properties.

Here is the default implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* from the TemplateProvider.cs file provided by Windows PowerShell.

Things to Remember About Implementing Set-ItemProperty

The following conditions may apply to an implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty*:

When defining the provider class, a Windows PowerShell property provider might declare provider capabilities of ExpandWildcards, Filter, Include, or Exclude, from the System.Management.Automation.Provider.Providercapabilities enumeration. In these cases, the implementation of the System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* method must ensure that the path passed to the method meets the requirements of the specified capabilities. To do this, the method should access the appropriate property, for example, the System.Management.Automation.Provider.Cmdletprovider.Exclude* and System.Management.Automation.Provider.Cmdletprovider.Include* properties.
By default, overrides of this method should not retrieve a reader for objects that are hidden from the user unless the System.Management.Automation.Provider.Cmdletprovider.Force* property is set to true. An error should be written if the path represents an item that is hidden from the user and System.Management.Automation.Provider.Cmdletprovider.Force* is set to false.
Your implementation of the System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* method should call System.Management.Automation.Provider.Cmdletprovider.ShouldProcess and verify its return value before making any changes to the data store. This method is used to confirm execution of an operation when a change is made to system state, for example, renaming files. System.Management.Automation.Provider.Cmdletprovider.ShouldProcess sends the name of the resource to be changed to the user, with the Windows PowerShell runtime and handling any command-line settings or preference variables in determining what should be displayed.

After the call to System.Management.Automation.Provider.Cmdletprovider.ShouldProcess returns true, if potentially dangerous system modifications can be made, the System.Management.Automation.Provider.Ipropertycmdletprovider.Setproperty* method should call the System.Management.Automation.Provider.Cmdletprovider.ShouldContinue method. This method sends a confirmation message to the user to allow additional feedback to indicate that the operation should be continued.

Attaching Dynamic Parameters for the Set-ItemProperty Cmdlet

The Set-ItemProperty cmdlet might require additional parameters that are specified dynamically at runtime. To provide these dynamic parameters, the Windows PowerShell property provider must implement the System.Management.Automation.Provider.Ipropertycmdletprovider.Setpropertydynamicparameters* method. This method returns an object that has properties and fields with parsing attributes similar to a cmdlet class or a System.Management.Automation.Runtimedefinedparameterdictionary object. The null value can be returned if no dynamic parameters are to be added.

Here is the default implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Getpropertydynamicparameters* from the TemplateProvider.cs file provided by Windows PowerShell.

Clearing Properties

To clear properties, the Windows PowerShell property provider must implement the System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* method to support calls from the Clear-ItemProperty cmdlet. This method sets one or more properties for the item located at the specified path.

Here is the default implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* from the TemplateProvider.cs file provided by Windows PowerShell.

Thing to Remember About Implementing ClearProperty

The following conditions may apply to your implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty*:

When defining the provider class, a Windows PowerShell property provider might declare provider capabilities of ExpandWildcards, Filter, Include, or Exclude, from the System.Management.Automation.Provider.Providercapabilities enumeration. In these cases, the implementation of the System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* method needs to ensure that the path passed to the method meets the requirements of the specified capabilities. To do this, the method should access the appropriate property, for example, the System.Management.Automation.Provider.Cmdletprovider.Exclude* and System.Management.Automation.Provider.Cmdletprovider.Include* properties.
By default, overrides of this method should not retrieve a reader for objects that are hidden from the user unless the System.Management.Automation.Provider.Cmdletprovider.Force* property is set to true. An error should be written if the path represents an item that is hidden from the user and System.Management.Automation.Provider.Cmdletprovider.Force* is set to false.
Your implementation of the System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* method should call System.Management.Automation.Provider.Cmdletprovider.ShouldProcess and verify its return value before making any changes to the data store. This method is used to confirm execution of an operation before a change is made to system state, such as clearing content. System.Management.Automation.Provider.Cmdletprovider.ShouldProcess sends the name of the resource to be changed to the user, with the Windows PowerShell runtime taking into account any command line settings or preference variables in determining what should be displayed.

After the call to System.Management.Automation.Provider.Cmdletprovider.ShouldProcess returns true, if potentially dangerous system modifications can be made, the System.Management.Automation.Provider.Ipropertycmdletprovider.Clearproperty* method should call the System.Management.Automation.Provider.Cmdletprovider.ShouldContinue method. This method sends a confirmation message to the user to allow additional feedback to indicate that the potentially dangerous operation should be continued.

Attaching Dynamic Parameters to the Clear-ItemProperty Cmdlet

The Clear-ItemProperty cmdlet might require additional parameters that are specified dynamically at runtime. To provide these dynamic parameters, the Windows PowerShell property provider must implement the System.Management.Automation.Provider.Ipropertycmdletprovider.Clearpropertydynamicparameters* method. This method returns an object that has properties and fields with parsing attributes similar to a cmdlet class or a System.Management.Automation.Runtimedefinedparameterdictionary object. The null value can be returned if no dynamic parameters are to be added.

Here is the default implementation of System.Management.Automation.Provider.Ipropertycmdletprovider.Clearpropertydynamicparameters* from the TemplateProvider.cs file provided by Windows PowerShell.

Building the Windows PowerShell provider

See How to Register Cmdlets, Providers, and Host Applications.