Sunday, February 03, 2008 2:33 PM bart

Easy Windows PowerShell cmdlet development and debugging

Before posting another post in the Windows PowerShell domain, I thought it was useful to write down the way to write a simple cmdlet in Visual Studio, with easy iterative debugging support. I've used this recipe myself quite a bit, including in on-stage presentations where you want to avoid messing up things at any cost :-).


Step 1 - Create a Class Library project

In Visual Studio, create a new Class Library project in the language of your choice (e.g. C#).



Step 2 - Import references

Next, we need to reference two assemblies. The first one is the System.Management.Automation assembly from Windows PowerShell. If you've installed the Windows SDK on your machine, you'll find it under %programfiles%\Reference Assemblies\Windows Powershell\v1.0:


Add a reference to it:


Next, add a reference to System.Configuration.Install because our cmdlet needs installer support in order to register its snap-in (see below):


Solution Explorer should look like this now:



Step 3 - Write the basics of the cmdlet

In the Class1.cs file of your project (feel free to rename obviously), write your first cmdlet by deriving from Cmdlet:


Use the smart tip to import System.Management.Automation:


Finally implement the basic cmdlet by overriding ProcessRecord:


And adding some code to it:


Finally don't forget to add the CmdletAttribute to it (in practice use VerbsCommon to get a list of common verbs to be used as the cmdlet verb instead of my "Say" verb below which isn't standard PS vocab):



Step 5 - Add a snap-in

Snap-ins are used to deploy a set of cmdlets, providers, etc as a management package. Creating one is easy by adding a class deriving from PSSnapIn, which is an abstract class with three properties:


Don't forget to attribute it with RunInstaller(true) which requires to import System.ComponentModel:




Step 6 - Build and register the snap-in

Build the solution, and open a Visual Studio Command Prompt running as Administrator. Go to the bin\Debug output folder of your project and invoke installutil -i on the compiled assembly as shown below:



Step 7 - Set up a debugging console for our snap-in

Now launch Windows PowerShell and invoke get-pssnapin -registered (don't forget -registered!) to see that our registration was successful:


In the screenshot above we've also added the snap-in using add-pssnapin MySnapIn and tested it by invoking our say-hello cmdlet. Next we export the console configuration to a psc1 (PowerShell Console v1) file:


This is an XML file containing the configuration of a PowerShell console with respect to imported snap-ins, as show below:



Step 8 - Hook up the debugger

Close Windows PowerShell and go back to our project. Open the Project Properties and go to the Debug tab. In here, specify the program to launch as Windows PowerShell and the arguments to be -PSConsoleFile <path to your debug.psc1 file>:


To test, set a breakpoint in our cmdlet and hit F5:


Invoke the cmdlet from the started Windows PowerShell instance:


The breakpoint is hit! Mission completed...Happy cmdlet debugging! | Digg It | Technorati | Blinklist | Furl | reddit | DotNetKicks

Filed under:


# Method invocation cmdlets in Windows PowerShell

Sunday, February 03, 2008 3:16 PM by B# .NET Blog

Introduction It should be a common introduction slogan for Windows PowerShell in the meantime, but let

# re: Easy Windows PowerShell cmdlet development and debugging

Monday, February 04, 2008 1:34 PM by Garth Arnold

A clear 'cookbook' example - very useful, thanks for posting !

# The custom MSBuild task cookbook

Friday, February 15, 2008 11:03 PM by B# .NET Blog

A few years ago I wrote about building custom MSBuild tasks . I wanted to bring the topic back in the

# The managed installer custom actions cookbook

Friday, February 15, 2008 11:48 PM by B# .NET Blog

While I&#39;m in the mood of writing up those cookbook posts: The custom MSBuild task cookbook Easy Windows

# Invoking PowerShell scripts from MSBuild

Saturday, February 16, 2008 2:22 AM by B# .NET Blog

I&#39;m a firm believer of the &quot;innovation through integration&quot; theme. As a fan of MSBuild

# The managed MMC 3.0 snap-in cookbook

Wednesday, February 27, 2008 12:04 AM by B# .NET Blog

My recent series of &quot;cookbook&quot; posts has been very well-received and coincidentally I got mail

# Tiny IIS Manager - Layering MMC 3.0 snap-ins on top of Windows PowerShell

Thursday, February 28, 2008 2:25 AM by B# .NET Blog

Back in manageability land. On TechEd EMEA Developers 2007 I delivered a talk on &quot;Next-generation

# Windows PowerShell 2.0 Feature Focus - Script cmdlets

Saturday, March 22, 2008 9:09 AM by B# .NET Blog

Two weeks ago I did a little tour through Europe spreading the word on a couple of our technologies including

# LINQ through PowerShell

Saturday, June 07, 2008 8:44 PM by B# .NET Blog

In a reaction to my post on LINQ to MSI yesterday, Hal wrote this: I don&#39;t know enough about the

# TechEd 2008 South Africa Demo Resources

Saturday, August 09, 2008 7:39 AM by B# .NET Blog

Last week, I had the honor to speak at TechEd 2008 South Africa on a variety of topics. In this post

# Windows Powershell | Trends Pics

Wednesday, February 23, 2011 4:06 AM by Windows Powershell | Trends Pics

Pingback from  Windows Powershell | Trends Pics

# Powershell by hobbestobias - Pearltrees

Friday, January 06, 2012 9:46 PM by Powershell by hobbestobias - Pearltrees

Pingback from  Powershell by hobbestobias - Pearltrees

# Powershell by markmmullin - Pearltrees

Friday, January 06, 2012 9:46 PM by Powershell by markmmullin - Pearltrees

Pingback from  Powershell by markmmullin - Pearltrees

# 5 steps to a better Windows command line | 53 Bytes - by Justin Beckwith

Pingback from  5 steps to a better Windows command line  | 53 Bytes - by Justin Beckwith