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!
Del.icio.us |
Digg It |
Technorati |
Blinklist |
Furl |
reddit |
DotNetKicks
Filed under: Windows PowerShell