How to Write a Custom PowerShell Cmdlet - Part II

Introduction

In How to Write a Custom PowerShell Cmdlet - Part I, I discussed the first step in writing a custom cmdlet. Now that you have written your cmdlet, you need to figure out how you are going to install it. I will explain that in this article.

You will be writing a PowerShell Snap-in to register your custom cmdlet. This is done by creating a new class derived from CustomPSSnapIn or PSSnapIn. From a high level, the difference between the two is that a snap-in derived from the PSSnapIn class will register all the cmdlets found in your assembly. Whereas snap-ins derived from CustomPSSnapIn allow the flexibility to pick and choose what cmdlets from your assembly you want to register. If you are developing only one cmdlet, then you can just derive from PSSnapIn and let it handle all the details about picking what to register. But, if you are developing multiple cmdlets in an assembly and you are not ready to register all of them and want to have a choice, then you will derive from the CustomPSSnapIn class. So, for my sample cmdlet, I have multiple cmdlets and there are few of them that are not ready for prime time. So, I derived my snap-in from CustomPSSnapIn.

public class AmazonPSSnapIn : CustomPSSnapIn {...}

When you derive from CustomPSSnapIn, there are four properties that you have to implement.

• Description: Supply a short description of your snap-in here.
• Name: Supply the name of your snap-in here.
• Vendor: Supply the vendor information for your snap-in here.
• Cmdlets: This is where you provide the collection of cmdlets that need to be registered. I will discuss this in detail next.

Cmdlets

This property expects you to return generic collection Collection to the installer utility. CmdletConfigurationEntry lets you define the configuration for your snap-in. At the very least, you will be providing the following three pieces of data to this object.

• Name: This is a very important parameter where you specify the name by which your cmdlet will be known to the user. In my example, for one of the cmdlets, I chose the name Get-Book. And, users call this command to perform the book search.
• ImplementingType: This is the most important property that you need to set for the CmdletConfigurationEntry object. This is where you define the type of the .NET object that has the implementation of your cmdlet.
• HelpFileName: You will be setting the file name that contains the help information for your cmdlet. This property is not as crucial as the first two because your cmdlet will work without any help information. You will just have to make sure that your users know how to user your cmdlet. But, it is important that you do provide help information for your cmdlet. That way, users can call get-help {cmdname} to get help for your cmdlet. I will be explaining how to write a help file for a cmdlet in my next article.

The following code snippet shows how I implemented the Cmdlets property to register three cmdlets from an assembly.

public override Collection Cmdlets
{
 get
 {
  if (null == _cmdlets)
  {
   _cmdlets = new Collection();
   _cmdlets.Add(new CmdletConfigurationEntry
     ("Get-Book", typeof(GetBookCommand), "AmazonPS.dll-Help.xml"));
   _cmdlets.Add(new CmdletConfigurationEntry
       ("Get-DVD", typeof(GetDVDCommand), "AmazonPS.dll-Help.xml"));
   _cmdlets.Add(new CmdletConfigurationEntry
       ("Get-DigitalMusic", typeof(GetDigitalMusicCommand), "AmazonPS.dll-Help.xml"));
   }
   return _cmdlets;
  }
}

How to register

Compile your cmdlet project. From the PowerShell command window, perform the following action (the following steps as described in the documentation):

PS> set-alias installutil $env:windir\Microsoft.NET\Framework\v2.0.50727\installutil
PS> installutil MyCustomCmdlets.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 registration

Once you successfully execute the above step, you can verify if your snap-in has been registered or not by executing the following command from the PowerShell window:

get-PSsnapin -registered

Add the snap-in to use it

Now that the snap-in has been registered, you are at the last step of adding your snap-in into PowerShell to start using it. Execute the following command from PowerShell to add your snap-in:

add-pssnapin MyCustomSnapIn

Save the configuration

Once you close the PowerShell command window, your add process will be lost. You will not lose the registration of your snap-in though. What this means is that the next time you start the PowerShell command window, you will have to execute the add-pssnapin command again to use your cmdlet. To solve this problem, you can export the configuration of your shell after adding the snap-in into the file. And, on subsequent sessions, you can use that configuration so that your custom cmdlet is already added to the shell.

export-console MyCustomCmdletPowerShell

Unregister and remove it

If you need to upgrade your custom cmdlet, you would want to remove it from the shell. You can execute the following command to remove it:

remove-PSSnapin MyCustomSnapIn

Make sure that the name matches the one that you used to add it. Otherwise, the shell will throw an error telling that this snap-in was not found. It is very important that you unregister your snap-in from the shell if you want to install an updated copy of it. Perform the following action at the PowerShell command prompt for unregistration:

PS> set-alias installutil $env:windir\Microsoft.NET\Framework\v2.0.50727\installutil
PS> installutil /u MyCustomCmdlets.dll

Notice that this step is identical to the step that you performed for registration. The difference is that you are specifying a /u argument to the InstallUtil command.

In my next article, I will discuss how to write a configuration file to customize the view of the output from your cmdlet.