How To Write Custom Powershell Cmdlet - Part 2

In How to write Cmdlet I discussed first step in writing a custom Cmdlet. Now you have written your Cmdlet, you need to figure out how you are going to install it. I will explain that in this artcle.

You will be writing a Powershell Snap-in to facilitate register your custom Cmdlet. This is done by creating a new class derived from CustomPSSnapIn or PSSnapIn class. From a high leevel the difference between two is that snap-in derived PSSnapIn class will register all the Cmdlets found in your assembly. Where are snap-in derived from CustomPSSnapIn allows 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 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 short description of your Snap-in here.
  • Name: Supply name of your Snap-in here.
  • Vendor: Supply vendor information for your Snap-in here.
  • Cmdlets: This is where you provide collection of Cmdlets that need to be registered. I will discuss this in details.

Cmdlets

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

  • Name: This is very important parameter where you specify the name by which your Cmdlet will be known to user. For example in my example for one of the Cmdlet I chose the name Get-Book. And users call this command to perform book search.
  • ImplementingType: This is the most important property that you need to set for CmdletConfigurationEntry object. This is where you define type of .Net object that has implementation of your Cmdlet.
  • HelpFileName: You will be setting file name that contains help information for your Cmdlet. This property is not as crucial as 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 you write help file for Cmdlet in next article.

Following code snipper shows how I implemented Cmdlets property to register three Cmdlets from 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

Comppile your Cmdlet project. From Powershell command window perform following action.(following steps as described in 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 executed above step, you can verify if your snap-in has been registered or not by executing following command from Powershell window.

get-PSsnapin -registered

Add To Use It

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

add-pssnapin MyCustomSnapIn

Save Configuration

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

export-console MyCustomCmdletPowerShell

Unregister and Remove It

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

remove-PSSnapin MyCustomSnapIn

Make sure that the name matches the one that you used to add it. Otherwise shell throw an error telling that this snap-in is not found. It is very important that you unregister your Snap-in from shell if you want to install a updated copy of it. Peform following action at 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 step is identical to step that you performed for registration. The difference is that you are specifying /u argument to InstallUtil command.

Sample Project

You can download the sample project from first article located at How to write Cmdlet

In next article I will discuss how you will write configuration file to customize view of output from your Cmdlet.

Search

Social

Weather

Monthly Posts