How to create PowerShell CmdLet ?
What is PowerShell CmdLet learn at Microsoft site for
CmdLet .
Create class library project.
Reference System.Management.Automation from PowerShell folder.
Typically
C:\Program Files (x86)\Reference Assemblies\Microsoft\WindowsPowerShell\3.0\System.Management.Automation.dll on x64 system
CmdLet is class inherited from PSCmdlet class (System.Management.Automation namespace).
We need some attributes to describe our CmdLet, at least something like:
[Cmdlet(VerbsCommon.Remove, "Controller")]
Decorating class with this attribute will create Cmdlet which can be invoked by typing
Remove-Controller.
PowerShell CmdLet common Verbs and custom Verb
VerbsCommon class from System.Management.Automation contains set of common verbs i.e. Add, Clear,Get,Set and if you want to use verb which is not defined, attribute declaration will look like:
[Cmdlet("Specify", "Controller")]
This will create Cmdlet which can be invoked by typing
Specify-Controller.
CmdLet parameters
If you need parameters in your Cmdlet you will declare them as class properties decorated with Parameter attribute i.e.:
[Parameter(Mandatory = true)]
public int ControllerId {get;set;}
CmdLet ProcessRecord method
In order to perform some work when CmdLet is invoked we need to override method:
protected virtual void ProcessRecord();
and we will do it like:
protected override void ProcessRecord()
{
WriteObject(String.Format("You have entered {0}", ControllerId));
base.ProcessRecord();
}
Importing PowerShell Module
Start Windows PowerShell and import module by issuing command:
Import-Module pathtodll
If you used non-common verb (like in our example) you will receive warning
WARNING: The names of some imported commands from the module 'PowershellPlayground' include unapproved verbs that might make them less discoverable. To find the commands with unapproved verbs, run the Import-Module command again with the Verbose parameter. For a list of approved verbs, type Get-Verb.
Your CmdLet is now available in this specific workspace. If you close Windows PowerShell window and open new, module will not be imported.
Let's run it by typing in PowerShell
Specify-Controller
As we marked ControllerId mandatory PowerShell will prompt:
cmdlet Specify-Controller at command pipeline position 1
Supply values for the following parameters:
ControllerId:
After you enter value you will have your value printed.
Optional CmdLet parameters
Let's change decoration of our parameter:
[Parameter(Mandatory = false)]
public int ControllerId { get; set; }
Rebuild. Import module to workspace and run Specify-Controller.
PowerShell will not prompt to enter parameter value and will print:
You have entered 0
Let's play but more and change parameter decoration once more:
[Parameter(Mandatory = false)]
public int? ControllerId { get; set; }
Rebuild, import module and run
Specify-Controller
Have in mind that rebuild will fail if you have PowerShell workspace with imported dll as PowerShell locks imported file.
PowerShell will print
You have entered
Let's run command with parameter specified:
Specify-Controller -ControllerId 2
Powershell will print:
You have entered 2
Write object from CmdLet
Let's create new class in our project
public class Response
{
public int Number { get; set; }
public DateTime TimeProcessed { get; set; }
public string Machine { get; set; }
}
and change ProcessRecord implementation
protected override void ProcessRecord()
{
var response = new Response
{
Number = ControllerId,
TimeProcessed = DateTime.Now,
Machine = Environment.MachineName
};
WriteObject(response);
base.ProcessRecord();
}
Rebuild, import and run
Specify-Controller -ControllerId 4
Response will be
Number TimeProcessed Machine
------ ------------- -------
4 29.10.2014 9:39:43 LIGHTNING
Let's change our Response class
public class Response
{
[DisplayName("Time processed")]
public DateTime TimeProcessed { get; set; }
public string Machine { get; set; }
public int? Number { get; set; }
public string Property1 { get; set; }
public string Property2 { get; set; }
public string Property3 { get; set; }
public string Property4 { get; set; }
public string Property5 { get; set; }
public string Property6 { get; set; }
public string Property7 { get; set; }
public string Property8 { get; set; }
public string Property9 { get; set; }
public string Property10 { get; set; }
}
Rebuild, import module and run
Specify-Controller -ControllerId 4
Result is:
TimeProcessed : 29.10.2014 9:45:41
Machine : LIGHTNING
Number : 4
Property1 :
Property2 :
Property3 :
Property4 :
Property5 :
Property6 :
Property7 :
Property8 :
Property9 :
Property10 :
We can see that display name is not affecting how PowerShell prints object. We can also see that order of properties will be same as order in which they are specified in class.
CmdLet Parameter from Pipeline
Let's create another Cmdlet
using System.Management.Automation;
namespace PowershellPlayground
{
[Cmdlet(VerbsCommon.Get,"CalculatedValue")]
public class ExampleCmdLet2 : PSCmdlet
{
[Parameter(Mandatory = true, Position = 1, ValueFromPipeline = true)]
public Response response { get; set; }
protected override void ProcessRecord()
{
response.Number += 10;
WriteObject(response);
base.ProcessRecord();
}
}
}
We have defined one parameter of Response type, mandatory and we have indicated that we will be able to receive this value from pipeline. Rebuild, import module and run:
Specify-Controller -ControllerId 5
Response will be
TimeProcessed : 29.10.2014 9:54:55
Machine : LIGHTNING
Number : 5
Now run
Specify-Controller -ControllerId 5 | Get-CalculatedValue
Response will be:
TimeProcessed : 29.10.2014 9:55:11
Machine : LIGHTNING
Number : 15
Create PowerShell Snap-in
To create PowerShell Snap-in we need to add extra class to our project. Here's example:
using System.ComponentModel;
using System.Management.Automation;
namespace PowershellPlayground
{
[RunInstaller(true)]
public class PowerShellPlayground : PSSnapIn
{
public override string Description
{
get { return "Playing with PowerShell"; }
}
public override string Name
{
get { return "PlayingWithPowerShell"; }
}
public override string Vendor
{
get { return "MCo"; }
}
}
}
This class inherits abstract class PSSnapIn and overrides few properties talking about our Snap-in. Class is actual installer so it needs to be marked with RunInstaller(true).
Rebuild solution.
Installing PowerShell Snapin
In order to make PowerShell aware of our Snap-in we need to install it using installutil:
From PowerShell:
Set-Alias installutil C:\windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe
installutil
pathtodll
Uninstalling PowerShell Snapin
From PowerShell:
Set-Alias installutil C:\windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe
installutil -u
pathtodll
Check that Snap-In is installed
Execute PowerShell CmdLet
Get-PSSnapin -Registered
You should be able to see following entry
Name : PlayingWithPowerShell
PSVersion : 3.0
Description : Playing with PowerShell
Add PSSnapin to workspace
Execute PowerShell CmdLet:
Add-PSSnapin PlayingWithPowerShell
List commands available in CmdLet
Execute PowerShell CmdLet:
Get-Command -PSSnapin PlayingWithPowerShell
Get all command with specific verb
Execute PowerShell CmdLet:
Get-Command -Verb Specify
Read more about Get-Command
at Microsoft site.
Get detailed information on CmdLet usage
Execute PowerShell CmdLet:
Get-Help Specify-Controller
Response will be:
NAME
Specify-Controller
SYNTAX
Specify-Controller [-ControllerId <int>] [<CommonParameters>]
ALIASES
None
REMARKS
None
Override PowerShell CmdLet
You can override CmdLet by crating one with same name. We will override
Get-WSManInstance CmdLet.
Let's create our CmdLet
using System.Management.Automation;
namespace PowershellPlayground
{
[Cmdlet(VerbsCommon.Get, "WSManInstance")]
public class GetWsManInstance : PSCmdlet
{
protected override void ProcessRecord()
{
WriteObject("Hello World!");
base.ProcessRecord();
}
}
}
Rebuild but do not import.
Start PowerShell and run
Get-WSManInstance
PowerShell will respond with
cmdlet Get-WSManInstance at command pipeline position 1
Supply values for the following parameters:
ResourceURI:
This is "default" implementation from Microsoft.WSMan.Management module.
Lets import our module:
Import-Module pathtodll
Run
Get-WSManInstance
And PowerShell will respond with
Hello World!
If you have multiple overrides of same CmdLet imported in PowerShell workspace last CmdLet imported will be one that will be executed.
