Problem
You want to write your own PowerShell cmdlet.
Discussion
As mentioned previously in “Structured Commands (Cmdlets)” in A Guided Tour of Windows PowerShell, PowerShell cmdlets offer several significant advantages over traditional executable programs. From the user’s perspective, cmdlets are incredibly consistent—and their support for strongly typed objects as input makes them powerful. From the cmdlet author’s perspective, cmdlets are incredibly easy to write when compared to the amount of power they provide. Creating and exposing a new commandline parameter is as easy as creating a new public property on a class. Supporting a rich pipeline model is as easy as placing your implementation logic into one of three standard method overrides.
While a full discussion on how to implement a cmdlet is outside the scope of this book, the following steps illustrate the process behind implementing a simple cmdlet.
For more information on how to write a PowerShell cmdlet, see the MSDN topic, “How to Create a Windows PowerShell Cmdlet,” available at http://msdn2.microsoft. com/enus/library/ms714598.aspx .
Step 1: Download the Windows SDK
The Windows SDK contains samples, tools, reference assemblies, templates, documentation, and other information used when developing PowerShell cmdlets. It is available by searching for “Microsoft Windows SDK” on http://download.microsoft. com and downloading the latest Windows Vista SDK.
Step 2: Create a file to hold the cmdlet and snapin source code
Create a file called InvokeTemplateCmdletCommand.cs with the content from Example 1512 and save it on your hard drive.
Example 1512. InvokeTemplateCmdletCommand.cs
using System; using System.ComponentModel; using System.Management.Automation;
/* To build and install:
1) SetAlias csc $env:WINDIR\Microsoft.NET\Framework\v2.0.50727\csc.exe
2) SetAlias installutil `
$env:WINDIR\Microsoft.NET\Framework\v2.0.50727\installutil.exe 3) $ref = [PsObject].Assembly.Location csc /out:TemplateSnapin.dll /t:library InvokeTemplateCmdletCommand.cs /r:$ref
4) installutil TemplateSnapin.dll
5) AddPSSnapin TemplateSnapin
To run:
PS >InvokeTemplateCmdlet
To uninstall:
installutil /u TemplateSnapin.dll
*/
namespace Template.Commands
{ [Cmdlet("Invoke", "TemplateCmdlet")] public class InvokeTemplateCmdletCommand : Cmdlet {
[Parameter(Mandatory=true, Position=0, ValueFromPipeline=true)] public string Text {
get { return text; }
Example 1512. InvokeTemplateCmdletCommand.cs (continued)
set { text = value;
} } private string text;
protected override void BeginProcessing() { WriteObject("Processing Started"); }
protected override void ProcessRecord() { WriteObject("Processing " + text); }
protected override void EndProcessing() { WriteObject("Processing Complete."); } }
[RunInstaller(true)] public class TemplateSnapin : PSSnapIn {
public TemplateSnapin()
: base() { }
///<summary>The snapin name which is used for registration</summary> public override string Name {
get { return "TemplateSnapin";
} } /// <summary>Gets vendor of the snapin.</summary> public override string Vendor {
get { return "Template Vendor";
} } /// <summary>Gets description of the snapin. </summary> public override string Description
Example 1512. InvokeTemplateCmdletCommand.cs (continued)
{ get {
return "This is a snapin that provides a template cmdlet."; } } } }
Step 3: Compile the snapin
APowerShell cmdlet is a simple .NET class. The DLL that contains the compiled cmdlet is called a snapin.
SetAlias csc $env:WINDIR\Microsoft.NET\Framework\v2.0.50727\csc.exe $ref = [PsObject].Assembly.Location csc /out:TemplateSnapin.dll /t:library InvokeTemplateCmdletCommand.cs /r:$ref
Step 4: Install and register the snapin
Once you have compiled the snapin, the next step is to register it. Registering a snapin gives PowerShell the information it needs to let you use it. This command requires administrative permissions.
SetAlias installutil ` $env:WINDIR\Microsoft.NET\Framework\v2.0.50727\installutil.exe installutil TemplateSnapin.dll
Step 5: Add the snapin to your session
Although step 4 registered the snapin, PowerShell doesn't add the commands to your active session until you call the AddPsSnapin cmdlet. AddPsSnapin TemplateSnapin
Step 6: Use the snapin
Once you've added the snapin to your session, you can call commands from that snapin as though you would call any other cmdlet.
PS >"Hello World" | InvokeTemplateCmdlet Processing Started Processing Hello World Processing Complete.
