How to Register Cmdlets, Providers, and Host Applications

Article
08/10/2009

This section describes how to add cmdlets, providers, and host applications to Windows PowerShell. The easiest way to add these components is through the use of modules (introduced by Windows PowerShell 2.0). A module is a collection of resources that can be defined by an assembly or script.

In most cases, use modules to add elements (including existing snap-in assemblies), however you can still add cmdlets and providers directly using snap-ins.

How to Add Resources Using Modules
How to Add Cmdlets and Providers Using Snap-ins
How to Add Components To a Custom Shell

Extending the Shell Using a Snap-in

Generally, you will register cmdlets, providers, and hosting applications through the use of Windows Powershell snap-ins. This registration mechanism does not require a new shell, but adds the cmdlets, providers, or hosting applications to the current session or a saved session. A Windows Powershell snap-in can register all the cmdlets and providers in a single assembly, or it can register a specific list of cmdlets and providers. For more information about Windows Powershell snap-ins, Windows PowerShell Snap-ins.

Note that your snap-in assembly should be installed into a protected directory just as you would with other operating system programs; otherwise, an unauthorized user could replace your assembly with malicious code.

Writing a Snap-in

To write a snap-in that registers all the cmdlets and providers in an assembly, your snap-in class must derive from the PSSnapIn class. For an example of writing this type of snap-in, see Writing a Windows PowerShell Snap-in.

To write a snap-in that registers a specific list of cmdlets and providers, your snap-in class must derive from the CustomPSSnapIn class. For an example of writing this type of snap-in, see Writing a Custom Windows PowerShell Snap-in.

Compiling the Snap-in Source File

To compile the Windows Powershell snap-in source file from the Windows PowerShell shell, you need to create a reference to the System.Management.Automation.dll library (you need a reference to this library in the source file as well), create a reference to the compiler, and then compile the source file.

The following entries show the commands used to compile the source file for the sample Select-String snap-in. If you copy this code, substitute "SelectStrCommandSample.cs" with the name of your snap-in source file.

PS> $ref = "$Env:ProgramFiles\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0\System.Management.Automation.dll"
PS> $compiler = "$env:windir/Microsoft.NET/Framework/v2.0.50727/csc"
PS> &$compiler /target:library /r:$ref SelectStrCommandSample.cs

Be aware that the Windows PowerShell™ reference assemblies are downloaded onto disk (by default at C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0).They are not installed in the Global Assembly Cache (GAC).

Register the Snap-in Library

Using the Windows Powershell snap-in library (.DLL file), register the snap-in by entering the following information on the command line, substituting the names for your Windows Powershell snap-in. Note that this step only creates registration information for the Windows Powershell snap-in. You still need to add the snap-in (described later) to use the cmdlets.

If you were using a third-party snap-in, this step would probably be handled by the installer for the corresponding application.

Warning

The version of the InstallUtil program that you must use varies depending on whether you are installing on a 32-bit or 64-bit platform.

To install 32-bit registry information, use: %systemroot%\Microsoft.NET\Framework\v2.0.50727\installutil.exe.

To install 64-bit registry information, use: %systemroot%\Microsoft.NET\Framework64\v2.0.50727\installutil.exe.

PS> set-alias installutil $env:windir\Microsoft.NET\Framework\v2.0.50727\installutil
PS> installutil SelectStrCommandSample.dll
Microsoft (R) .NET Framework Installation utility Version 2.0.50727.42
Copyright (C) Microsoft Corporation. All rights reserved.
Running a transacted installation.
…
The transacted install has completed.

Verify that the Windows PowerShell Snap-in is Registered

You can verify that the snap-in is registered using the Get-PSSnapIn cmdlet shown below. When the cmdlet is called with the Registered parameter, Windows PowerShell displays the currently loaded snap-ins, followed by a list of registered snap-ins that can be added. Your snap-in should be in this list.

PS> get-PSsnapin -registered

Add the Snap-in to the Shell

Now you can add the Windows Powershell snap-in to the shell using the Add-PSSnapin cmdlet as shown below. If the operation is successful, you should be able to run your cmdlet.

PS> add-pssnapin SelectStrPSSnapIn

Preserve the Snap-in Configuration

After you add a snap-in to the shell, you can save this configuration so that subsequent Windows PowerShell sessions will include the current snap-ins. The Export-Console cmdlet creates a console file (.psc1) that identifies the snap-ins to load when the shell starts. You can enter the following on the command line to save the currently loaded snap-ins to the console file.

PS> export-console MyCustomShell

The previous command creates a MyCustomShell.psc1 file in the current directory. If this particular configuration is no longer required, you only have to remove the console file.

Start the Shell from a Saved Configuration

To start Windows PowerShell using the snap-ins in use during an earlier session, you can use the entry shown below. The information can be entered either from the command line or as part of a shortcut.

C:\Program Files\Command Shell> PS -PSConsoleFile MyCustomShell.mcf

Remove a Snap-in

You can use the Remove-PSsnapin cmdlet to remove a snap-in from the shell. Removal disables the cmdlets and providers provided by the snap-in. The following example illustrates the removal of the snap-in for the sample Select-Str cmdlet.

Note

Never attempt to remove the system snap-ins provided by Windows PowerShell.

PS> remove-PSsnapin SelectStrPSSnapIn
PS> select-str
'select-str' is not recognized as a Cmdlet, function, operable program, or script file.
At line:1 char:11
+ select-str <<<<

Register with a Custom Shell

When you register a cmdlet, Windows PowerShell provider, or hosting application with a custom shell, you are essentially building a new version of the Windows PowerShell.exe application that includes the assembly for your program module. Note that Windows PowerShell will run only one version of an assembly at a time. Therefore, you will have to reregister with a custom shell for each new version of the program module.

To register your program module with a custom shell, type the information shown below to invoke the correct Windows PowerShell variables, substituting information specific to your module. The following information is for the sample Select-Str cmdlet.

PS> $ref = "$Env:ProgramFiles\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0\System.Management.Automation.dll"
PS> $compiler = "$env:windir/Microsoft.NET/Framework/v2.0.50727/csc"
PS> &$compiler /target:library /r:$ref SelectStrCommandSample.cs.cs

Now it is necessary to rebuild the shell. You can do this using a utility called Make-Shell included with Windows PowerShell. For more information about Make-Shell, access its Help by typing make-shell /? on the command line.

PS> make-shell –out NewPS -namespace Microsoft.Samples.PS -reference SelectStrCommandSample.dll
Microsoft Command Shell Makekit
Copyright (C) 2005 Microsoft Corporation. All rights reserved.

Shell NewPS.exe is created successfully.
PS>

You can now invoke the new shell to run your program module. It can be run either standalone or loaded into another application.

PS> NewPS.exe

Partager via