Invoking a PowerShell Command from within a program–How Do They DO That?

One of the aspects of the Monad Manifesto was its advocating building GUIs on top of PowerShell. For some devs and fewer IT Pros, the mechanism is pretty clear and straightforward. But for a lot, it’s a bit of a black art. In this article, I’ll look at how they do that, but I’ll demostrate by doing it in PowerShell (with a pointer to seeing it in C#).

Running PowerShell within your executable program (irrespective of it being a GUI or a console application), involves 3 objects:

• Runspace – a runspace is the operating environment pipelines. A pipeline runs within a runspace.
• Pipeline – a pipeline is used to invoke commands.
• Command – a cmdlet or script that gets added to a pipeline to run in a run space

Each of these three objects are found within the System.Management.Automation.RunSpaces namespace and are pretty easy to create and manage. The descriptions of these objects in MSDN are a little thin in and could usefully be improved with more examples.

Here’s a script that illustrates this (analysis is below the script)

###
#   Create a PowerShell runspace and open it
$rs = [System.Management.Automation.Runspaces.RunspaceFactory]::CreateRunspace()
$rs.open()

#   Create a Pipeline
$Pipeline= $rs.CreatePipeline()

#   Create a command and add parameters
$cmd = New-Object system.management.automation.runspaces.command "Get-Process"
$cmd.Parameters.Add("Name", "Power*")

#   Add the first command to the Pipeline
$Pipeline.Commands.Add($cmd)

#   Invoke the pipeline
$collection = $pipeline.invoke()

#   See what's there
$collection
###

So what does this script do? Well first, it uses the runspace factory ( a feature built into .NET)  to create a new runspace on the local machine. Once created, the script opens the runspace for use.

Next we use the runspace object to create a new pipeline. We create a new  command object using New-Object. The command object is meant to run the  Get-Process  cmdlet and has a parameter (-Name) which for this run will have a value of ‘Power*’). 

After the command is added to the pipeline, the pipeline is invoked. Invoking the pipelines involves PowerShell, in effect, to run the Get-Process cmdlet with the appropriate parameters and return a result. That result, which is the same as you get running the command locally, is an array of objects that match the globbed name parameter (i.e. it would match PowerShell, PowerShell_ISE, PowerPoint, etc).

If you want the pipeline to have more than one command, that’s easy too. Suppose you wanted to support the output we obtained above? In other words, suppose you want to get the effect of “Get-Process –Name Power* | Sort-Object –Property CPU”? That’s easy. Just before invoking the pipeline above, just add the following:

#    Create a second command and add parameters
$cmd2 = new-object system.management.automation.runspaces.command "Sort-Object"
$cmd2.Parameters.Add("Property", "CPU")

#    Add the second command to the Pipeline
$pipeline.Commands.Add($cmd2)

It’s actually pretty easy, if you understand how to manage the three key objects involved. If you think about it, the sequence the script goes through is pretty much what PowerShell itself is doing when you are sitting at the console. The console is a little more complex, but most of the real magic is in the runspace itself and that is something the script and developers in general just leverage the feature.

An interesting aspect here is that all three objects are created using different approaches. The runspace is created by a static method on the runspace factory class, the pipeline was obtained by calling the runspace object’s method, CreatePipeline, and the command object(s) are created using New-Object.

So where might this be useful to an IT Pro. Probably not a lot of direct use – since PowerShell is doing all this for you (i.e. creating the run space, managing the pipeline and pipeline commands within, and marshal the output from the execution into something sensible at the console).  But I hope this might be of assistance to developers that are getting into PowerShell for the first time and want to integrate it into their applications.

Technorati Tags: PowerShell,Runspace,Pipeline,Command,Pipeline Command,Runspace Factory,.NET