concept pipeline in category powershell

PowerShell connects commands to each other by using a pipeline. The pipeline provides a way for one command to pass, or pipe, its output to another command, allowing that second command to have something to work with.

At this point, you’ve learned to be pretty effective with PowerShell’s pipeline. Running commands (for example, Get-Process | Sort-Object VM -desc | ConvertTo-Html | Out-File procs.html) is powerful, accomplishing in one line what used to take several lines of script. But you can do even better. In this chapter, we dig deeper into the pipeline and uncover some of its most powerful capabilities which allow you to pass data beteween commands the right way with less work.

With this method of pipeline parameter binding, PowerShell looks at the type of object produced by Command A and tries to see whether any parameter of Command B can accept that type of object from the pipeline. You can determine this for yourself: First pipe the output of Command A to Get-Member, to see what type of object Command A is producing. Then examine the full help of Command B (for example, Get-Help Get-Command -Full) to see whether any parameter accepts that type of data from the pipeline ByValue. Figure 10.2 shows what you might discover.

Figure 10.2 Comparing the output of Get-Content to the input parameters of Get-Command

What you’ll find is that Get-Content produces objects of the type System.String (or String for short). You’ll also find that Get-Command does have a parameter that accepts String from the pipeline ByValue. The problem is that it’s the -Name parameter, which according to the help “specifies an array of names. This cmdlet gets only commands that have the specified name.” That isn’t what we want—our text file, and therefore our String objects, are module names, not command names. If we ran the following

What are the two ways PowerShell can pass data from one command to another in the pipeline?

Take traditional pipeline behavior from shells like Bash and Cmd.exe. Mix in Power-Shell’s unique object-oriented nature. Add a dash of Linux-style command parsing. The result? PowerShell’s pipeline, a fairly complex and deeply powerful tool for composing tools into administrative solutions. To be a toolmaker is to understand the pipeline at its most basic level, and to create tools that take full advantage of the pipeline. Although we covered these concepts in Learn Windows PowerShell in a Month of Lunches, in this chapter we’ll go deeper and focus on the pipeline as something to write for, rather than to just use.

DEBUG: ParameterBinding Information: 0 : PIPELINE object TYPE =
[System.String]
DEBUG: ParameterBinding Information: 0 : RESTORING pipeline
parameter's original values

copy

PowerShell identifies the type of object in the pipeline as a System.String. Take a minute and read the full help for Out-Null. Do you see any parameters capable of accepting a String from the pipeline using the ByValue method?

Figure 4.1. Visualizing the pipeline

Figure 1.5. Anatomy of a pipeline

1.5. How the pipeline works

A pipeline is a series of commands separated by the pipe operator (|), as shown in figure 1.5. In some ways, the term production line better describes pipelines in PowerShell. Each command in the pipeline receives an object from the previous command, performs some operation on it, and then passes it along to the next command in the pipeline.

Figure 1.5. Anatomy of a pipeline

PS> $word = New-Object -ComObject Word.Application -Strict
New-Object : The object written to the pipeline is an instance of the type
   "Microsoft.Office.Interop.Word.ApplicationClass"  from the component's
   primary interoperability assembly. If this type exposes different members
   than the IDispatch members, scripts that are written to work with this
   object might not work if the primary interoperability assembly is not
   installed.
At line:1 char:9
+ $word = New-Object -ComObject Word.Application -Strict
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    + CategoryInfo          : InvalidArgument: (Microsoft.Offic...pplication
  Class:ApplicationClass) [New-Object], PSArgument
   Exception
    + FullyQualifiedErrorId : ComInteropLoaded,Microsoft.PowerShell.Commands.NewObjectCommand

copy

So far, you’ve been working with only simple commands, but one of PowerShell’s greatest strengths is the ability to build pipelines of commands. In this section, we’re going to look at how to do that with the PowerShell API.

To create a pipeline with more than one command, all you need to do is to make a subsequent call to AddCommand() for each additional command you want to add to the pipeline. Each command you add becomes the next stage in the pipeline. Let’s see how this works with another example. In this example, you’re going to convert this pipeline

Adding scripts to the pipeline

We’ve looked at adding single commands, with or without parameters, and arguments to build pipelines using the PowerShell API. Now we’re going to look at another way of adding executable content to the [PowerShell] instance. As well as commands, the PowerShell API allows you to add scripts to an instance. As you might expect by now, this is done through the AddScript() method.

Instead, when two PowerShell commands are connected to each other, the first command places its output, in the form of objects, into the pipeline. The pipeline is something that the shell itself maintains as a way of getting objects from one command to another. In a way, the pipeline is a bit like StdOut; it’s the one place that all PowerShell commands must send their output.

Each parameter can accept only a certain kind of input, which is also documented in the help. The –Name parameter accepts objects of the type String, whereas the -InputObject parameter accepts objects of the type ServiceController. PowerShell looks at the objects in the pipeline to see what type they are. You can do the same thing by using the Get-Member cmdlet:

PS C:\> Get-Service | Get-Member

   TypeName: System.ServiceProcess.ServiceController

Name                      MemberType    Definition
----                      ----------    ----------
Name                      AliasProperty Name = ServiceName
RequiredServices          AliasProperty RequiredServices = ServicesDepen...
Disposed                  Event         System.EventHandler Disposed(Sys...

copy

The first line of output says it all: Get-Service produces objects of the type System .ServiceProcess.ServiceController. As a shortcut, you usually just look at the last part of the name, which is ServiceController. That’s the exact type of object that -InputObject will accept ByValue, and so, as shown in figure 8.4, PowerShell sends the objects in the pipeline to the –InputObject parameter. The help file for Stop-Service says that the –InputObject parameter

That’s right, Stop-Process has only one parameter that accepts pipeline input ByValue, and it’s –InputObject. Unfortunately, the help file says that this parameter accepts objects of the type Process. That isn’t what you have in the pipeline, and you can’t turn a ServiceController into a Process so ByValue will fail. On to Plan B!

Now the shell looks to see which parameters accept pipeline input ByPropertyName. It also does the internal equivalent of running Get-Member again, to see what properties the objects in the pipeline have. Figure 8.7 shows this step.

Figure 8.7. PowerShell starts trying ByPropertyName binding by listing the properties of the objects in the pipeline.

PropertyName is simple: The values from every property of every object in the pipeline will be sent to any parameters that have the same name. In this case, only two Stop-Process parameters work with ByPropertyName: -Name and –ID. The objects in the pipeline don’t have an ID property, so the –ID parameter gets nothing. The objects in the pipeline have a Name property, so that property’s values get attached to the –Name parameter, simply because the property name matched the parameter name!

You’ll also see periodic exchanges about the state of the pipeline. The following indicates that the command is done:

Param() block—Provides example parameters (and a reminder to insert comment-based help for the parameter). Note that it’s valid to write Function name (Param1, Param2) {body} in PowerShell, but not if [CmdletBinding()] is specified; in that case you must use a param() block. One of the example parameters accepts input from the pipeline.

Begin{}, Process{} and End{} blocks—Used when input comes from the pipeline. Begin runs before the first item, Process repeats for each item, and End runs after the last item.

When PowerShell became available in Exchange Server 2007, I converted the code to PowerShell. It took me about 30 minutes, most of which was starting the virtual machine (this was when Exchange Server 2007 was in beta) and looking up the appropriate cmdlets. Those 86 lines of VBScript condensed to one line of PowerShell that consisted of three cmdlets linked on the pipeline. A pipeline is a method of passing data from one command to another. It is covered in detail later in the chapter.

Figure 1.3. The PowerShell pipeline in action. The objects pass along the pipeline, which controls their processing by the individual cmdlets. The PowerShell parser uses the code to tell the cmdlets what actions should be performed.