[PowerShell] Write a Custom PowerShell Cmdlet in C#

Particularly with SharePoint 2010, I have become a huge fan of Microsoft PowerShell. In addition to writing complex PowerShell scripts (.ps1 files), I have found it very useful to write my own C#-based PowerShell Cmdlets to use in my scripts.

This basic tutorial illustrates how to create a basic PowerShell Cmdlet with a couple of parameters. In the future, I will be adding addition posts about more indepth topics. However, this tutorial should get you started if you are new to writing PowerShell Cmdlets.

For this tutorial I am using Visual Studio 2010. In addition, you will need the PowerShell SDK installed (comes with the Windows 7 SDK if you have installed that instead).

1. In Visual Studio 2010, create a new Class Library project targeted to .NET Framework 3.5 (Visual C# > Windows > Class Library). OPTIONAL: For consistency, I recommend naming the project with the name of the actions. For instance, if you want to create a “Get-MyPsCmdlet” command, name the project “MyPsCmdlet”.

2. Delete the Class1.cs file included by default.

3. Add a reference to System.Management.Automation.dll (you will need to browse to the assembly at C:\Program Files (x86)\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0).

4. In the Solution Explorer right-click the project name and select Add > Class.

5. Create a new class named with the command and the verb. For instance, for “Get-MyPsCmdlet” name your class file “MyPsCmdletGet.cs”.

6. Add “System.Management.Automation” in the usings statements and set the basetype of the class to Cmdlet as follows:

   [csharp]using System;
   using System.Management.Automation;

   namespace MyPsCmdlet
   {
   [Cmdlet(VerbsCommon.Get, “MyPsCmdlet”)]
   public class MyPsCmdletGet : Cmdlet
   {

   }
   }[/csharp]

7. Above the class declaration, you will notice “[Cmdlet(VerbsCommon.Get, “MyPsCmdlet”)]”. In these properties you can define the name, verb, default parameter set, etc., of the Cmdlet. Using the “Get” common verb and “MyPsCmdlet” will result in a command of “Get-MyPsCmdlet”. There are a number of common verb sets that you may use. For consistence with help documentation and localization, it is important to use a common verb whenever possible. If a common verb does not fit your needs, you can populate that value with a string of your choice.

   Verb Sets:

   • VerbsCommon
   • VerbsCommunications
   • VerbsData
   • VerbsDiagnostic
   • VerbsLifecycle
   • VerbsOther
   • VerbsSecurity

8. To add your code to run when the command is executed, simply override the “ProcessRecord()” method:

   [csharp]using System;
   using System.Management.Automation;

   namespace MyPsCmdlet
   {
   [Cmdlet(VerbsCommon.Get, “MyPsCmdlet”)]
   public class MyPsCmdletGet : Cmdlet
   {
   protected override void ProcessRecord()
   {
   // Your code goes here
   }
   }
   }[/csharp]

9. In the Cmdlet you can write text to the console like any other console application with “Console.Write” or “Console.WriteLine”. However, most PowerShell Cmdlets return objects. Here we have a simple object named “MyObject” that we are returning to the console:

   [csharp]using System;
   using System.Management.Automation;

   namespace MyPsCmdlet
   {
   [Cmdlet(VerbsCommon.Get, “MyPsCmdlet”)]
   public class MyPsCmdletGet : Cmdlet
   {
   protected override void ProcessRecord()
   {
   var myobj = new MyObject()
   {
   Name = “My Object”,
   Created = DateTime.Now
   };

   WriteObject(myobj);
   }
   }

   public class MyObject
   {
   public string Name { get; set; }
   public DateTime Created { get; set; }
   }
   }[/csharp]

10. With PowerShell Cmdlets you can add parameters of just about any .NET type. In this instance:

    • “public SwitchParameter CreatedTomorrow” is used to define a flag parameter for the Cmdlet. There is no value passed, it simply exists or does not exists. For example: “Get-MyPsCmdlet -CreatedTomorrow”.
    • “public MyObject MyObj” is used to create a parameter that requires an object with “MyObject” as the type. For example: “$myobj = Get-MyPsCmdlet”, then “Get-MyPsCmdlet -MyObj $myobj”.
    • “public string ObjectName” is used to create a parameter that requires a string. For values with spaces, use quotations around the string.

    [csharp]using System;
    using System.Management.Automation;

    namespace MyPsCmdlet
    {
    [Cmdlet(VerbsCommon.Get, “MyPsCmdlet”)]
    public class MyPsCmdletGet : Cmdlet
    {
    [Parameter(Mandatory = false)]
    public SwitchParameter CreatedTomorrow;

    [Parameter(Mandatory = false)]
    public MyObject MyObj;

    [Parameter(Mandatory = false)]
    public string ObjectName;

    protected override void ProcessRecord()
    {
    var myobj = new MyObject()
    {
    Name = “My Object”,
    Created = DateTime.Now
    };

    if (CreatedTomorrow.IsPresent)
    myobj.Created = DateTime.Now.AddDays(1);

    if (!string.IsNullOrEmpty(ObjectName))
    myobj.Name = ObjectName;

    if (MyObj != null)
    myobj = MyObj;

    WriteObject(myobj);
    }
    }

    public class MyObject
    {
    public string Name { get; set; }
    public DateTime Created { get; set; }
    }
    }[/csharp]

11. Now that we have our Cmdlet writen, we can build and run it. In Visual Studio, build the project.

12. Open PowerShell.

13. Import the assembly using Import-Module:

    [powershell]Import-Module C:\Files\Projects\MyPsCmdlet\MyPsCmdlet\bin\Debug\MyPsCmdlet.dll[/powershell]

14. Run the Cmdlet:

    [powershell]Get-MyPsCmdlet[/powershell]

That’s it. You now have a fully functional PowerShell Cmdlet. Stay tuned for more advanced PowerShell Cmdlet posts.