Creating a Windows PowerShell Property Provider
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 tofalse
.
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 tofalse
.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 tofalse
.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.
See Also
Design Your Windows PowerShell provider
PowerShell