Chapter 20. Your Own Cmdlets and Extensions

Since PowerShell is layered on the .NET framework, you already know from Chapter 6 how you can use .NET code in PowerShell to make up for missing functions. In this chapter, we'll take up this idea once again. You'll learn about the options PowerShell has for creating command extensions on the basis of the .NET framework. You should be able to even create your own cmdlets at the end of this chapter.

Topics Covered:

• Compiling Your Own .NET Expansions
  • Extension for the Clipboard
  • In-Memory Compiling
  • DLL Compilation
• Building Your Own Cmdlets
  • How Cmdlets Are Structured
  • Step 1: Compiling the Snap-In
  • Step 2: Registering Snap-Ins
  • Step 3: Loading Snap-Ins
• The Structure of Cmdlets
  • The Snap-In
  • The Cmdlet
  • Begin, Process, End

Compiling Your Own .NET Expansions

Many functionalities of the .NET framework are available right in PowerShell. For example, the following two lines suffices to set up a dialog window:

In Chapter 6, you learned in detail about how this works and what an "assembly" is. To briefly explain what happened here, PowerShell used LoadWithPartialName() to load a system library and was then able to use the classes from it to call a static method like MsgBox().

That's extremely practical when there is already a system library that offers the method you're looking for, but for some functionality even the .NET framework doesn't have any right commands. For example, you have to rely on your own resources if you want to move text to the clipboard. The only way to get it done is to access the low-level API functions outside the .NET framework.

Extension for the Clipboard

As soon as you need more than just a few lines of code or access to API functions to implement the kinds of extensions you want, it makes sense to write the extension directly in .NET program code. The following example shows how a method called CopyToClipboard() might look in VB.NET. The VB.NET code is directly assigned in the form of a Here string to the $code variable:

You have to first compile the code before PowerShell can execute it. Compilation is a translation of your source code into machine-readable intermediate language (IL). There are two options here.

In-Memory Compiling

In a very simple case, you can task PowerShell to use CompileAssemblyFromSource() to translate your source code directly in a memory. The result is a new .NET assembly. As soon as the assembly is compiled, PowerShell can use the methods in it as well as CopyToClipboard() to move text to the clipboard:

DLL Compilation

You'll lose your compilation in the memory as soon as you end PowerShell, which means you would have to do everything all over again every time you need the CopyToClipboard() method. An often better approach is to compile your source code in a Dynamic Link Library (DLL), whose file can then be loaded whenever you need it or passed on to friends and colleagues.

To make a DLL file from your source code, call the vbc.exe VB.NET compiler directly:

The result is the sourcecode.dll file. If you want to put it to work, all you have left to do now is to use LoadFrom() to load it in PowerShell:

Building Your Own Cmdlets

Command extensions based on DLLs that you compile yourself are an interesting alternative, but somewhat unwieldy. You would have to already know exactly where to find the DLL, use LoadFrom() to load it, and still have to know which method in the assembly is the right one. A further disadvantage is that methods from external DLLs don't support the PowerShell pipeline.

Your command extension will work much more conveniently if you turn it into a cmdlet. Your own new cmdlet will behave just like cmdlets that already exist. You can put it to work inside the pipeline, and it won't require any unusual method invocations.

How Cmdlets Are Structured

Every cmdlet represents a single command. These are wrapped as a package in the form of a snap-in so that PowerShell can use your cmdlets. The following example makes use of your clipboard function above in the Out-Clipboard cmdlet and wraps this in the ClipboardSnapin snap-in. A little later, it will be explained just how the following source code works. First, take a look at what steps are necessary to make this source code into a functioning cmdlet:

Step 1: Compiling the Snap-In

As in the first examples, your source code must first be compiled. Again, use the vbc.exe VB.NET compiler. However, because your cmdlet uses classes like Cmdlet and PSSnapIn, which PowerShell provides, the compiler has to be given a reference to the PowerShell libraries. Use the /reference switch to give this reference. The simplest way to find the location of the PowerShell libraries is to query the Assembly.Location property of the PSObject type.

If you haven't made any typing errors in $code of your source code, you'll get the file cmdlet.dll: your new snap-in, which includes your cmdlet.

Step 2: Registering Snap-Ins

Before you can use a snap-in, it has to be registered. The installutil.exe utility program of the .NET framework handles registration. Using it is roughly like using regsvr32.exe to register COM components in the old COM world. It makes some registry entries so that PowerShell can find your snap-in later.

The following lines implement registration:

Step 3: Loading Snap-Ins

You use the Get-PSSnapin cmdlet to manage all registered snap-ins. This cmdlet allows you to find out which snap-ins that you are currently using:

As you see, all cmdlets come from snap-ins. Even the tightly built-in cmdlets are not at all as tightly built-in as it seems. When PowerShell starts, it loads them from various snap-ins. So, it might be that some additional snap-ins are on your system, such as to manage Microsoft Exchange or to perform other tasks.

But Get-PSSnapin not only displays snap-ins that are already loaded, but any others as well. Using the -registered parameter instructs Get-PSSnapin to list all registered snap-ins. Since you already registered your own snap-in, it should be in this list:

If you want to use a new snap-in, you have to load it using Add-PSSnapin. You need to do it once for every PowerShell session so, if you need the snap-in often, you should get it to automatically load right into one of your PowerShell profile scripts (see Chapter 10).

As soon as the snap-in is loaded, all the cmdlets it contains will be available. You could call your new Out-Clipboard cmdlet to move text to the clipboard:

It may also be used inside the pipeline since your cmdlet supports the PowerShell pipeline. The next line will copy your output to the clipboard:

However, if you insert text from the clipboard into a program like Notepad, you may ask why just the file name and not the complete directory listing are displayed.

The answer lies in the PowerShell pipeline, which, remember, transports objects. The result of Dir is individual objects, while Out-Clipboard is expecting text. That's why only one object property, the name, is passed onto the clipboard. If you really want to move the entire directory listing in the form in which it is normally displayed in the console to the clipboard, you should first use Out-String to convert the objects into text:

By the way, your new cmdlet also supports many other aspects of cmdlets like debugging messages. If you specify the -debug parameter, your cmdlet will output all the reports that were written to your source code using WriteDebug(). Depending on the debugging settings in $debugpreference, you can either have your computer ask you to confirm each step or just show yellow-colored debugging messages.

The Structure of Cmdlets

Now, let's look a little more closely at the source code of your cmdlet, which actually consists of three classes:

• Snap-Ins: The first class defines the snap-in, that is, the general container for all following cmdlets.
• Cmdlet: The second class defines the Out-Clipboard cmdlet.
• Helper classes: Finally, the third class corresponds to clipboard functionality and is used by the cmdlet to copy text to the clipboard.

The Snap-In

The snap-in enables installation of the cmdlet package using the RunInstaller attribute. The installutil registration tool can automatically enter this snap-in in the registry.

The second task of the snap-in is to retrieve information about maker, version, and function of the package. The ClipboardSnapin class is derived from the PSSnapin prototype using Inherit so that this information can be called for every snap-in while always using the same properties. This enables the class to be assigned standard properties that the class later defines more precisely using Overrides.

The Cmdlet

The actual cmdlet is an additional class that is derived this time from the Cmdlet prototype. The Cmdlet attribute defines the name of the cmdlet. Only certain names are allowed as verbs because the names of all cmdlets obey strict naming rules. That's why the verb out comes from the VerbsData list, which sets the permitted name. In contrast, the noun part of the name can be freely selected and is specified as Clipboard. As a result, the complete name of this cmdlet is Out-Clipboard.

There follow the parameters of the cmdlet. In this case, only one parameter called Text is set. Its position is 0, which means that if no parameter name is specified, Out-Clipboard will bind the first specified argument to the parameter. For this reason, you may type both Out-Clipboard -text Hello and Out-Clipboard Hello.

So that your cmdlet can also get input from the pipeline, ValueFromPipeline is set to True,making it possible for you to use your cmdlet inside the pipeline: Dir | Out-Clipboard.

Begin, Process, End

In conclusion, you should specify what will happen when your cmdlet is called. Like the functions we saw in Chapter 9, three phases must be distinguished. BeginProcessing() is called when the cmdlet is activated (initialization). EndProcessing() is called when the cmdlet has ended its work (tidying tasks). And ProcessRecord() is called for every single object that is passed to the cmdlet.

It is best for you to look at what happens in practice by calling your cmdlet using the -debug parameter, which enables you to read the debugging messages that are in your source text with WriteDebug() and that tell you exactly when each part was executed.