We can create commands/cmdlets using C# or combine commands in ps1 files (for example) but we can also implement Powershell functions, which give is the ability to combine existing Powershell commands but wrap them in their own function with their own help etc.

Let’s look at a simple implementation of a tail-like command

Get-Content -Path c:\logs\logfile.log -Wait 

Ofcourse the first thing we might like to do is wrap this in a simple function, like this

function Get-Tail 
{ 
   Get-Content -Path $args[0] -Wait 
}

This works fine, but now maybe we’d like to make it more obvious what argument(s) Get-Tail expects. So we’ll add a parameter which better illustrates the intent via it’s name etc. So now we might have

function Get-Tail 
{ 
   param (
      [Parameter(Mandatory=$true, 
       Position=0, 
       HelpMessage="Path of file to tail")]
      [ValidateNotNullOrEmpty()]
      [string]$Path
   )

   Get-Content -Path $Path -Wait 
}

Here we’ve named the parameter that we expect as Path and we’ve stipulated it’s type. We’ve also added a Parameter attribute to ensure it’s obvious that this is a mandatory field and if the user forgets to supply it, Powershell will ask for it, to that purpose we’ve also supplied a help message so if the user types !? into the prompt for Path, the user will get the help message telling them what’s expected.

This is looking good, but running Get-Help tells us very little about the function so now we can extend this further and make it look like this

function Get-Tail 
{ 
<#
.SYNOPSIS
   Lists the file to standard out and waits 
   for any change which are then also output
.DESCRIPTION
   Get-Tail works a little like the tail 
   command, it allows the user to write a 
   file to standard out and then waits for
   any further changes, these to are written to
   standard out until the user exist the command.
.PARAMETER Path
   The Path to the file to be tailed
.EXAMPLE
   Get-Tail c:\logs\logfile.log
#>
param
(
[Parameter(Mandatory=$true, 
 Position=0, 
 HelpMessage="Path of file to tail")]
[ValidateNotNullOrEmpty()]
[string]$Path
)
 
Get-Content -Path $Path -Wait 
}

Now we have a command written in Powershell which looks and acts like any of the common commands might work, with help.

Let’s quickly review the lines we’ve added – the <# #> is the comment block for Powershell, within it we’ve headings along the lines of .HEADING and below that we’ve just some text to describe the command. The .PARAMETER is more interesting in that we write the parameter name after it (we can have multiple .PARAMETER blocks for multiple params).

To find out what options are available for the help block, type

Get-Help about_Comment_Based_Help

References

Documenting Your PowerShell Binary Cmdlets

So Powershell comes with a lot of commands/CmdLets but as a developer I’m always interested in how I might write my own. Whilst it’s likely that combining existing commands might produce the results you’re after, if it doesn’t we can resort to writing our own command using C#.

Getting Started

• Create a new Class Library project
• Go to the project properties and target the version of .NET supported by your installed version of Powershell (to find this out simply type $PSVersionTable into Powershell and check the CLRVersion)
• Add a reference to System.Management.Automation to locate this browse to C:\Program Files (x86)\Reference Assemblies\Microsoft\WindowsPowerShell\3.0
• The namespace we need to add is System.Management.Automation

Hello World CmdLet

Now we’ve got everything set-up we need to make our CmdLet do something. Here’s the source for a good old HelloWorld Cmdlet

[Cmdlet(VerbsCommon.Get, "HelloWorld")]
public class GetHelloWorld : Cmdlet
{
   protected override void ProcessRecord()
   {
      WriteObject("Hello World");
   }
}

The CmdLetAttribute takes a string for the verb, in this case I’m reusing the VerbsCommon.Get string. The next requirements is the noun, the name of the Cmdlet. So in this case the two go together to give us the Cmdlet Get-HelloWorld.

We derive our class from Cmdlet as we’re not dependent upon the Powershell runtime, if we were we’d derive from the PSCmdlet.

Importing and using the new CmdLet

Once we’ve built our CmdLet and assuming it’s been built with the same version of .NET as supported by the installed Powershell, we can import the “module” into Powershell using

Import-Module c:\Dev\MyCmdLets.dll

Obviously replacing the path and DLL with the location and DLL you’re installing

Once imported we can simply run

Get-HelloWorld

Autocomplete also works if you type Get-He then press tab and you’ll find Get-HelloWorld presented.

If you need to rebuild your Cmdlet you’ll need to close the Powershell instance to remove the instance from it, I tried Remove-Module MyCmdLets but this only removes its availability to Powershell, i.e. you can no longer run it, but I guess, like in C# applications, once the module is in the AppDomain you cannot fully unload it.

Parameters

Let’s add a parameter to the Cmdlet.

[Cmdlet(VerbsCommon.Get, "HelloWorld")]
public class GetHelloWorld : Cmdlet
{
   [Parameter(Mandatory = true)]
   public string Name { get; set; }

   protected override void ProcessRecord()
   {
      WriteObject("Hello World " + Name);
   }
}

So now, we’ve added a mandatory parameter Name. When we run the Get-HelloWorld Cmdlet we can now supply the name, thus

Get-HelloWorld -Name Scooby

Returning objects

So far we’ve returned a string, but what about if we want to return and object or better still multiple objects, like Get-Process might.

[Cmdlet(VerbsCommon.Get, "HelloWorld")]
public class GetHelloWorld : Cmdlet
{
   protected override void ProcessRecord()
   {
      WriteObject(new HelloObject { Name = "Scooby", Description = "Dog"} );
      WriteObject(new HelloObject { Name = "Shaggy", Description = "Man" });
      WriteObject(new HelloObject { Name = "Daphne", Description = "Woman" });
   }
}

public class HelloObject
{
   public string Name { get; set; }
   public string Description { get; set; }
}

Now running this from Powershell will list two columns, Name and Description and three rows with the name and description as per our objects.

Better still we can now write commands such as

Get-HelloWorld | where {$_.Description -eq "Dog"}

References

Cmdlet Methods

In a previous post I started to look into using Powershell, but ofcourse the power of commands/Cmdlets comes when they’re either combined or whereby our most common commands exist in files to be run again and again.

So let’s turn an often used command into a ps1 file.

Windows PowerShell ISE (Integrated Scripting Engine)

From the Windows search box (ctrl+R) we can run up the Windows PowerShell ISE. This gives us, both an editor and also a command prompt for writing and testing our command scripts.

You can also run this application from the command line using powershell_is or better still via the alias ise.

In the editor let’s type

Get-Process | where {$_.CPU -gt 1000}

Now save this file as Top-Cpu.ps1

Running our new command

We can simply drag and drop a ps1 file from Windows Explorer onto the Powershell window to fill in the fully qualified path on the command line, pressing enter we can then run the file. Obviously if you know the full path you can do this yourself by typing the same into the command prompt.

Specifying parameters

It may be that our ps1 file is perfect as it is, but it’s also quite likely we’ll want to allow the user to change some values in it at runtime, i.e. using command line arguments/parameters.

To specify parameters in our script we write

param(cpu=1000)

This defines a parameter named cpu and gives a default value, in this case 1000. If we change our script to look like this

param($cpu=1000)
Get-Process | where {$_.CPU -gt $cpu}

where you’ll notice $cpu is the placeholder/variable where the parameter is used. We can now run this script as Top-cpu.ps1 and the default parameter is used. Or we might write Top-cpu.ps1 7000 to supply a new parameter.

Multiple parameters

We can command separate our parameters to include multiple params, like this

param($value=1000, $field="CPU")
Get-Process | where {$_.$field -gt $value}

Maybe not so useful in this specific script, but you get the idea.

References

Windows PowerShell: Defining Parameters

What’s the purpose of the $profile

The $profile (like a bash script configuration) allows us to configure the way our Powershell command shell looks, or sets the default location, we can add commands and aliases etc.

Where’s the $profile and does it exist?

Typing the following will result in Powershell telling us where the Microsoft.PowerShell_profile.ps1 file is expected to be

$profile

Just because $profile outputs a path, does not mean there’s a file’s there. It’s simply telling us where it goes to get the profile, we may still need to created one, instead we can use the following

We can find out whether a $profile already exists using

Test-Path $profile

Test-Path determines whether all elements of a path exists, i.e. in this case, does the file exist

Creating the profile file

Typing

New-Item -path $profile -itemType file -force

will create a new item (in this case a file) at the location (and name) supplied by the $profile variable. The force switch ensure the file is overwritten if it already exists.

The ps1 file is just a text file, so from the command line you can run Notepad or powershell_ise (or ofcourse from the Windows GUI you can do the same) and edit the file, allow us to enter the commands that might want available from session to session.