Creating a Windows PowerShell Content Provider

 

This topic describes how to create a Windows PowerShell provider that enables the user to manipulate the contents of the items in a data store. As a consequence, a provider that can manipulate the contents of items is referred to as a Windows PowerShell content provider.

System_CAPS_noteNote

You can download the C# source file (AccessDBSampleProvider06.cs) for this provider using 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 [delete].

The downloaded source files are available in the <PowerShell Samples> directory.

For more information about other Windows PowerShell provider implementations, see Designing Your Windows PowerShell Provider.

The following list contains the sections in this topic. If you are unfamiliar with writing a Windows PowerShell content provider, read these sections in the order that they appear. However, if you are familiar with writing a Windows PowerShell content provider, go directly to the information that you need.

A Windows PowerShell content provider must create a .NET class that supports the IContentCmdletProvider interface. Here is the class definition for the item provider described in this section.

Note that in this class definition, the CmdletProviderAttribute attribute includes two parameters. The first parameter specifies a user-friendly name for the provider that is used by Windows PowerShell. The second parameter specifies the Windows PowerShell specific capabilities that the provider exposes to the Windows PowerShell runtime during command processing. For this provider, there are no added Windows PowerShell specific capabilities.

As described in Design Your Windows PowerShell Provider, the NavigationCmdletProvider class derives from several other classes that provided different provider functionality. A Windows PowerShell content provider, therefore, typically defines all of the functionality provided by those classes.

For more information about how to implement functionality for adding session-specific initialization information and for releasing resources that are used by the provider, see Creating a Basic Windows PowerShell Provider. However, most providers, including the provider described here, can use the default implementation of this functionality that is provided by Windows PowerShell.

To access the data store, the provider must implement the methods of the DriveCmdletProvider base class. For more information about implementing these methods, see Creating a Windows PowerShell Drive Provider.

To manipulate the items of a data store, such as getting, setting, and clearing items, the provider must implement the methods provided by the ItemCmdletProvider base class. For more information about implementing these methods, see Creating a Windows PowerShell Item Provider.

To work on multi-layer data stores, the provider must implement the methods provided by the ContainerCmdletProvider base class. For more information about implementing these methods, see Creating a Windows PowerShell Container Provider.

To support recursive commands, nested containers, and relative paths, the provider must implement the NavigationCmdletProvider base class. In addition, this Windows PowerShell content provider can attaches IContentCmdletProvider interface to the NavigationCmdletProvider base class, and must therefore implement the methods provided by that class. For more information, see implementing those methods, see Implement a Navigation Windows PowerShell Provider.

To read content from an item, a provider must implements a content reader class that derives from IContentReader. The content reader for this provider allows access to the contents of a row in a data table. The content reader class defines a Read method that retrieves the data from the indicated row and returns a list representing that data, a Seek method that moves the content reader, a Close method that closes the content reader, and a Dispose method.

To write content to an item, a provider must implement a content writer class derives from IContentWriter. The content writer class defines a Write method that writes the specified row content, a Seek method that moves the content writer, a Close method that closes the content writer, and a Dispose method.

To get content from an item, the provider must implement the GetContentReader to support the Get-Content cmdlet. This method returns the content reader for the item located at the specified path. The reader object can then be opened to read the content.

Here is the implementation of GetContentReader for this method for this provider.

The following conditions may apply to an implementation of GetContentReader:

  • When defining the provider class, a Windows PowerShell content provider might declare provider capabilities of ExpandWildcards, Filter, Include, or Exclude, from the ProviderCapabilities enumeration. In these cases, the implementation of the GetContentReader 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 Exclude and Include properties.

  • By default, overrides of this method should not retrieve a reader for objects that are hidden from the user unless the Force property is set to true. An error should be written if the path represents an item that is hidden from the user and Force is set to false.

The Get-Content cmdlet might require additional parameters that are specified dynamically at runtime. To provide these dynamic parameters, the Windows PowerShell content provider must implement the GetContentReaderDynamicParameters method. This method retrieves dynamic parameters for the item at the indicated path and returns an object that has properties and fields with parsing attributes similar to a cmdlet class or a RuntimeDefinedParameterDictionary object. The Windows PowerShell runtime uses the returned object to add the parameters to the cmdlet.

This Windows PowerShell container provider does not implement this method. However, the following code is the default implementation of this method.

To write content to an item, the provider must implement the GetContentWriter to support the Set-Content and Add-Content cmdlets. This method returns the content writer for the item located at the specified path.

Here is the implementation of GetContentWriter for this method.

The following conditions may apply to your implementation of GetContentWriter:

  • When defining the provider class, a Windows PowerShell content provider might declare provider capabilities of ExpandWildcards, Filter, Include, or Exclude, from the ProviderCapabilities enumeration. In these cases, the implementation of the GetContentWriter 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 Exclude and Include properties.

  • By default, overrides of this method should not retrieve a writer for objects that are hidden from the user unless the Force property is set to true. An error should be written if the path represents an item that is hidden from the user and Force is set to false.

The Add-Content and Set-Content cmdlets might require additional dynamic parameters that are added a runtime. To provide these dynamic parameters, the Windows PowerShell content provider must implement the GetContentWriterDynamicParameters method to handle these parameters. This method retrieves dynamic parameters for the item at the indicated path and returns an object that has properties and fields with parsing attributes similar to a cmdlet class or a RuntimeDefinedParameterDictionary object. The Windows PowerShell runtime uses the returned object to add the parameters to the cmdlets.

This Windows PowerShell container provider does not implement this method. However, the following code is the default implementation of this method.

Your content provider implements the ClearContent method in support of the Clear-Content cmdlet. This method removes the contents of the item at the specified path, but leaves the item intact.

Here is the implementation of the ClearContent method for this provider.

The following conditions may apply to an implementation of ClearContent:

  • When defining the provider class, a Windows PowerShell content provider might declare provider capabilities of ExpandWildcards, Filter, Include, or Exclude, from the ProviderCapabilities enumeration. In these cases, the implementation of the ClearContent 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 Exclude and Include properties.

  • By default, overrides of this method should not clear the contents of objects that are hidden from the user unless the Force property is set to true. An error should be written if the path represents an item that is hidden from the user and Force is set to false.

  • Your implementation of the ClearContent method should call 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 the data store, such as clearing content. The ShouldProcess method sends the name of the resource to be changed to the user, with the Windows PowerShell runtime handling any command-line settings or preference variables in determining what should be displayed.

    After the call to ShouldProcess returns true, the ClearContent method should call the ShouldContinue method. This method sends a message to the user to allow feedback to verify if the operation should be continued. The call to ShouldContinue allows an additional check for potentially dangerous system modifications.

The Clear-Content cmdlet might require additional dynamic parameters that are added at runtime. To provide these dynamic parameters, the Windows PowerShell content provider must implement the ClearContentDynamicParameters method to handle these parameters. This method retrieves the parameters for the item at the indicated path. This method retrieves dynamic parameters for the item at the indicated path and returns an object that has properties and fields with parsing attributes similar to a cmdlet class or a RuntimeDefinedParameterDictionary object. The Windows PowerShell runtime uses the returned object to add the parameters to the cmdlet.

This Windows PowerShell container provider does not implement this method. However, the following code is the default implementation of this method.

When writing a provider, it may be necessary to add members to existing objects or define new objects. When this is done, you must create a Types file that Windows PowerShell can use to identify the members of the object and a Format file that defines how the object is displayed. For more information, see see Extending Object Types and Formatting [ps].

When your Windows PowerShell provider has been registered with Windows PowerShell, you can test it by running the supported cmdlets on the command line. For example, test the sample content provider.

Use the Get-Content cmdlet to retrieve the contents of specified item in the database table at the path specified by the Path parameter. The ReadCount parameter specifies the number of items for the defined content reader to read (default 1). With the following command entry, the cmdlet retrieves two rows (items) from the table and displays their contents. Note that the following example output uses a fictitious Access database.

PS mydb:\> get-content -Path mydb:\Customers -ReadCount 2
ID        : 1
FirstName : Eric
LastName  : Gruber
Email     : ericgruber@fabrikam.com
Title     : President
Company   : Fabrikam
WorkPhone : (425) 555-0100
Address   : 4567 Main Street
City      : Buffalo
State     : NY
Zip       : 98052
Country   : USA
ID        : 2
FirstName : Eva
LastName  : Corets
Email     : evacorets@cohowinery.com
Title     : Sales Representative
Company   : Coho Winery
WorkPhone : (360) 555-0100
Address   : 8910 Main Street
City      : Cabmerlot
State     : WA
Zip       : 98089
Country   : USA
Show: