How-To: Cmdlet Pipelines and Filtering with the PowerShell SDK v2
This article is for the PowerShell SDK version 2.
In this article, we will cover the basics of pipelining cmdlets and using the filter parameter with the PowerShell SDK v2.
The use of cmdlet pipelines is only available in the PowerShell SDK version 2. Filtering is available in version 1 and version 2.
What are pipelines?
In basic terms, when you pipeline commands in PowerShell, you are sending the results from one command to another command by using the pipeline character "
|" (which is technically ASCII character 124). This allows for creating complex "pipelines" of commands that daisy-chains from one command to another. Visually, it looks like this:
Command 1 | Command 2 | Command 3 | Command 4 ...
Notice that we used the word "Command" and not "cmdlet". This is because a cmdlet in PowerShell is just a portion of the overall commands available. A pipeline could contain not only a cmdlet, but also any other command used within PowerShell that would accept pipeline input, or any command that would provide input to another command, such as an array.
As an example, we will do a simple pipeline that send the output from the Get-Process cmdlet for an application that is running, such as word.exe, to the Stop-Process cmdlet so the application is terminated. This is also an example of a cmdlet to cmdlet pipeline.
Get-Process -Name word.exe | Stop-Process
An example of using a pipeline to send output from a PowerShell
dir command to the PowerShell
measure-object command is shown below.
dir c:\scripts\*.ps1 -Recurse | measure-object -Property length –sum
You can read more about PowerShell pipelines in this Microsoft documentation.
Pipelines with the PowerShell SDK
Starting with our SDK version 2, we now have many of our PowerShell cmdlets that allow pipelines to be created. To determine if a cmdlet accepts pipelines for any of it's parameters, you will need to examine the Help context for that particular cmdlet. To do this, perform the following command, replacing the New-Pfa2Host with the cmdlet of your choice.
Get-Help -Name New-Pfa2Host -Parameter *
The output from that command will show you all of the parameters allowed for that cmdlet and what objects those parameters allow and disallow. This is an excerpt of that output showing both a parameter called
-Iqns that shows an
Accept pipeline input: False, as well as a parameter called
-Name that does allow for pipeline input:
-Iqns <List<String>> The iSCSI qualified name (IQN) associated with the host. Required? false Position? named Default value None Accept pipeline input? False Accept wildcard characters? false -Name <String> Performs the operation on the unique name specified. Required? false Position? named Default value None Accept pipeline input? True (ByPropertyName, ByValue) Accept wildcard characters? false
This means that when we want to use the New-Pfa2Host cmdlet for reporting on or executing commands against multiple hosts in an array, we can pipeline multiple
-Names to it without having to specify each one. This would be an example of a pipeline that sends an array of names to the New-Pfa2Host cmdlet like this:
$Hosts = @("host01","host02","host03") $Hosts | New-Pfa2Host -Array $array
Here is another example of a pipeline using the Get-Pfa2Host cmdlet and piping the output to the Remove-Pfa2Host cmdlet, effectvely removing all of the hosts on the array (this is a destructive command and should only be used when necessary).
Get-Pfa2Host -Array $array | Remove-Pfa2Host -Array $array
As you can see from these few examples, with the addition of pipelines in the SDK, you can accomplish more with less and produce more desirable output. For more examples, please see the Readme.md file included with the module.
The -Filter Parameter
The -Filter parameter was introduced in the SDK version 1 and it allows for the narrowing down of results from a cmdlet's output. If you are working with many arrays, even hundreds of arrays, filtering is something you will want to include in your scripts.
There is a specific file created and included with the module distribution called about_Pfa2Filtering.Help.txt that contains all of the information on this parameter and examples on how to use it.