Welcome Sign in
Microsoft Developer Network
Click to Rate and Give Feedback
MSDN
MSDN Library
How to Register Cmdlets, Providers, and Host Applications

This section describes how to register cmdlets, Windows PowerShell providers, and hosting applications with Windows PowerShell. There are two mechanisms that can be used to register cmdlets, providers, and hosting applications, with the first one being the default mechanism that will work in most situations. Use the second mechanism only to create a new executable file.

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 OS 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 Microsoft® 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.

Caution noteCaution:

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 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

See Also

Footer image

Send comments about this topic to Microsoft.

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Where is System.Management.Automation.dll?      JeremyMc   |   Edit   |  
I just downloaded PowerShell and System.Management.Automation.dll doesn't exist on my system. There is a System.Management.Automation-help.dll, but that's it. Is there another way to register cmdlets?
Found it in the PowerShell SDK....But still can't compile      JeremyMc   |   Edit   |  
I've got System.Management.Automation.dll now, but when I try to compile, I get an error: "error CS0246 The type or namespace 'PSSnapIn' could not be found" As far as I can tell, PSSnapIn should be in System.Management.Automation.dll..What's going on?
For help with system.management.automation...      Thomas Lee   |   Edit   |  
I suggest you ask these questions in the powershell newsgroup: microsoft.public.windows.powershell.

You can get this newsgroup on msnews.microsoft.com using any NNTP newsreader.

Alternatively, use the web interface at: http://www.microsoft.com/communities/newsgroups/list/en-us/default.aspx?dg=microsoft.public.windows.powershell. Or, if you are a Google fan, use http://groups.google.com/group/microsoft.public.windows.powershell/topics.

Hope this helps
For help with system.management.automation...      JeremyMc   |   Edit   |  
I posted to the Group and got my answer.

Here is a link to the post:
http://groups.google.com/group/microsoft.public.windows.powershell/browse_thread/thread/725962ef855ca921/0198ad905e7b3268#0198ad905e7b3268

The answer below:
junker37 wrote:
> I'm trying to compile a PSSnapIn using these directions:
> http://msdn2.microsoft.com/en-us/library/ms714644(VS.85).aspx

> I've taken the PSSnapIn found here: http://msdn2.microsoft.com/en-us/library/ms714453.aspx
> and named it GetProcSample.cs

The example is missing a few things to be valid C# source code (and to
actually compile):

At the start:
using System;
using System.Management.Automation;
using System.ComponentModel;
namespace foo_test <--Whatever you want
{

At the end:

}

That should get you going...

Marco

--
Microsoft MVP - Windows PowerShell
http://www.microsoft.com/mvp

PowerGadgets MVP
http://www.powergadgets.com/mvp

Blog:
http://marcoshaw.blogspot.com


© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker