{"id":16051,"date":"2010-12-31T00:01:00","date_gmt":"2010-12-31T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2010\/12\/31\/write-powershell-functions-that-accept-pipelined-input\/"},"modified":"2010-12-31T00:01:00","modified_gmt":"2010-12-31T00:01:00","slug":"write-powershell-functions-that-accept-pipelined-input","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/write-powershell-functions-that-accept-pipelined-input\/","title":{"rendered":"Write PowerShell Functions That Accept Pipelined Input"},"content":{"rendered":"

<\/span><\/p>\n

<\/span><\/p>\n

Summary:<\/span><\/b> Learn how to write Windows PowerShell functions that accept pipelined input.<\/span><\/p>\n

 <\/span><\/p>\n

\"Hey,<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>Hey, Scripting Guy! I really like the way that some Windows PowerShell cmdlets enable me to <\/span>pipeline<\/span><\/a> things to it. I do not understand why some Windows PowerShell cmdlets do not allow me to pipeline stuff to it, or perhaps I am doing it wrong. Anyway, my question is as follows: How can I write a function that will accept input from the pipeline? I think it would add a lot of additional capability to my functions, and enable them to behave more the way that Windows PowerShell, in general, tends to behave. <\/span><\/p>\n

— ES<\/span><\/p>\n

 <\/span><\/p>\n

\"Hey,<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>Hello ES, Microsoft Scripting Guy Ed Wilson here. One of the weird things about living in Charlotte, <\/span>North Carolina<\/span><\/a> is that the winters are generally very mild. Weird, some of my Canadian friends say, weird. After having lived in the Deep South for several years, I do, in fact, miss Winter. I imagine I would get tired of shoveling snow, scraping ice, and playing “bumper cars” on the freeway if I had to do it year after year, but as an occasional respite from the normal southern cloudy, cold, and drizzling rain that is the seasonal norm around here, I think I would like to take my chances. In fact, the time that the <\/span>Scripting Wife<\/span><\/a> and I spent in Quebec, Canada a few years ago when I was teaching Windows PowerShell workshops to Microsoft Premier Customers was our favorite winter. The following image is a picture I took of Quebec from an ice-breaking ferryboat as it crossed the <\/span>St. Lawrence River<\/span><\/a>. <\/span><\/p>\n

<\/span><\/p>\n

Of course, one’s perspective on winter depends a great deal upon where one is used to residing. My friends in Sydney, <\/span>Australia<\/span><\/a> are telling me on Facebook that it is 81 degrees Fahrenheit today (27 degrees Celsius). <\/span><\/p>\n

One of the most useful things I ever did, Windows PowerShell wise, was my conversion module. I use it almost every day to convert temperatures from Fahrenheit to Celsius and vice versa. Of course, it also converts distance, and volume in addition to other things. I developed it during the <\/span>first six Weekend Scripter articles<\/span><\/a>. If you only want to see the final product, check out <\/span>version six of the module<\/span><\/a>. <\/span><\/p>\n

ES, there are several ways that you can provide input values to a function. In today’s post, I will examine four ways. Two of the methods do not use the pipeline, and two of the methods do use the pipeline. As a quick review, using the pipeline in Windows PowerShell is a technique where the output of one command is streamed directly into the input of another command. A nice example of this would be to read a text file that contains a listing of directories (as seen in the following figure) and pipeline the results of reading the text file to the Get-ChildItem<\/b> Windows PowerShell cmdlet (Get-ChildItem<\/b> has the alias of dir<\/i>). <\/span><\/p>\n

H<\/span><\/p>\n

The command to perform this pipeline operation appears here.<\/span><\/p>\n

\n

PS C:\\> Get-Content C:\\fso\\Folders.txt | Get-ChildItem<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

If I want to configure my function to accept pipelined input, I can use the process directive. This has the advantage of simplicity, and in addition, it makes the script really easy to read. This is seen here.<\/span><\/p>\n

\n

Function add-oneD<\/span><\/span><\/p>\n

{<\/span><\/span><\/p>\n

 <\/span>Process { $_ + 1 }<\/span><\/span><\/p>\n

} #end function add-oneD<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

The add-oneD<\/b> function does not define any input parameters. Instead, it uses the $_ automatic<\/i> variable to accept the current value that is on the pipeline. To call this function, I can pipeline a group of numbers directly to the add-oneD<\/b> function. This is seen here.<\/span><\/p>\n

\n

1..5000000 | add-oneD<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

To check the performance of the function, I use the Measure-Command<\/b> Windows PowerShell cmdlet. This is seen here, along with the associated output.<\/span><\/p>\n

\n

Measure-command -Expression { 1..5000000 | add-oneD }<\/span><\/span><\/p>\n

Days              <\/span>: 0<\/span><\/span><\/p>\n

Hours             <\/span>: 0<\/span><\/span><\/p>\n

Minutes           <\/span>: 0<\/span><\/span><\/p>\n

Seconds           <\/span>: 35<\/span><\/span><\/p>\n

Milliseconds      <\/span>: 17<\/span><\/span><\/p>\n

Ticks             <\/span>: 350172660<\/span><\/span><\/p>\n

TotalDays         <\/span>: 0.000405292430555556<\/span><\/span><\/p>\n

TotalHours        <\/span>: 0.00972701833333333<\/span><\/span><\/p>\n

TotalMinutes      <\/span>: 0.5836211<\/span><\/span><\/p>\n

TotalSeconds      <\/span>: 35.017266<\/span><\/span><\/p>\n

TotalMilliseconds : 35017.266<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

It took around 35 seconds on my computer to add five million numbers – not too bad. But, perhaps I can make it perform a little better. The second way to configure the function to accept direct pipeline input is to use the $input<\/b> variable. As seen here, the add-oneC<\/b> function uses the <\/span>Foreach<\/span><\/i><\/a> command to iterate through the $input<\/b> automatic variable. When anything is piped to a function, the stream will be contained in the $input<\/b> variable. The add-oneC<\/b> function appears here.<\/span><\/p>\n

\n

Function add-oneC<\/span><\/span><\/p>\n

{<\/span><\/span><\/p>\n

 <\/span>foreach($a in $input)<\/span><\/span><\/p>\n

  <\/span>{ $a + 1 }<\/span><\/span><\/p>\n

} #end function add-oneC<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

To call the add-oneC<\/b> function, I use the same kind of command that I used when calling the add-oneD<\/b> function. I pipeline the numbers directly to the function. This command appears here.<\/span><\/p>\n

\n

1..5000000 | add-oneC<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

To measure the performance of the new function, I use the Measure-Command<\/b> Windows PowerShell cmdlet as seen here.<\/span><\/p>\n

\n

Measure-command -Expression { 1..5000000 | add-oneC }<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

The performance increase is remarkable. As seen here, the new function only takes a little more than fifteen seconds to add the five million numbers. <\/span><\/p>\n

\n

Days              <\/span>: 0<\/span><\/span><\/p>\n

Hours             <\/span>: 0<\/span><\/span><\/p>\n

Minutes           <\/span>: 0<\/span><\/span><\/p>\n

Seconds           <\/span>: 15<\/span><\/span><\/p>\n

Milliseconds      <\/span>: 455<\/span><\/span><\/p>\n

Ticks             <\/span>: 154554599<\/span><\/span><\/p>\n

TotalDays         <\/span>: 0.000178882637731481<\/span><\/span><\/p>\n

TotalHours        <\/span>: 0.00429318330555556<\/span><\/span><\/p>\n

TotalMinutes      <\/span>: 0.257590998333333<\/span><\/span><\/p>\n

TotalSeconds      <\/span>: 15.4554599<\/span><\/span><\/p>\n

TotalMilliseconds : 15455.4599<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

In a quest for performance, suppose I create the array of numbers, and pass the array directly to the function. Then inside the function I pipeline the items. Will this be faster? Here is the add-oneB <\/b>function.<\/span><\/p>\n

\n

Function add-oneB<\/span><\/span><\/p>\n

{<\/span><\/span><\/p>\n

 <\/span>Param ($a)<\/span><\/span><\/p>\n

 <\/span>$a | foreach-object { $_ + 1 }<\/span><\/span><\/p>\n

} #end add-oneB<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

To call this function, I first have to create an array with five million numbers in it, and then pass that array to the function. Here is the code that does that.<\/span><\/p>\n

\n

$a = 1..5000000<\/span><\/span><\/p>\n

add-oneB -a $a<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

When I call the Measure-Command<\/b> to check the performance, the results are a bit disappointing. Here is the command, and the results.<\/span><\/p>\n

\n

$a = 1..5000000<\/span><\/span><\/p>\n

Measure-command -Expression { add-oneB -a $a }<\/span><\/span><\/p>\n

Days              <\/span>: 0<\/span><\/span><\/p>\n

Hours             <\/span>: 0<\/span><\/span><\/p>\n

Minutes           <\/span>: 5<\/span><\/span><\/p>\n

Seconds           <\/span>: 20<\/span><\/span><\/p>\n

Milliseconds      <\/span>: 372<\/span><\/span><\/p>\n

Ticks             <\/span>: 3203725668<\/span><\/span><\/p>\n

TotalDays         <\/span>: 0.00370801581944444<\/span><\/span><\/p>\n

TotalHours        <\/span>: 0.0889923796666667<\/span><\/span><\/p>\n

TotalMinutes      <\/span>: 5.33954278<\/span><\/span><\/p>\n

TotalSeconds      <\/span>: 320.3725668<\/span><\/span><\/p>\n

TotalMilliseconds : 320372.5668<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

Three hundred and twenty seconds; <\/span>Dude<\/span><\/a> (or Dudette) that is more than five minutes – clearly this is not a very good approach to the problem. <\/span><\/p>\n

I decided to try one more approach, creating an array, and passing it to the function. Here is the add-oneA<\/b> function.<\/span><\/p>\n

\n

Function add-oneA<\/span><\/span><\/p>\n

{<\/span><\/span><\/p>\n

 <\/span>Param ($a)<\/span><\/span><\/p>\n

 <\/span>foreach($b in $a)<\/span><\/span><\/p>\n

  <\/span>{ $b + 1 }<\/span><\/span><\/p>\n

} #end function add-oneA<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

Again, I have to create the array with five million numbers in it, and pass it to the function. This is seen here.<\/span><\/p>\n

\n

$a = 1..5000000<\/span><\/span><\/p>\n

 <\/span><\/span><\/p>\n

add-oneA -a $a<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

To check the performance of the new function, I again call on the Measure-Command<\/b> Windows PowerShell cmdlet as seen here. <\/span><\/p>\n

\n

$a = 1..5000000<\/span><\/span><\/p>\n

 <\/span><\/span><\/p>\n

Measure-command -Expression { add-oneA -a $a }<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

The results this time are impressive (as seen here,) the function processed five million numbers in a little less than eight seconds.<\/span><\/p>\n

\n

Days              <\/span>: 0<\/span><\/span><\/p>\n

Hours             <\/span>: 0<\/span><\/span><\/p>\n

Minutes           <\/span>: 0<\/span><\/span><\/p>\n

Seconds           <\/span>: 7<\/span><\/span><\/p>\n

Milliseconds      <\/span>: 964<\/span><\/span><\/p>\n

Ticks             <\/span>: 79640050<\/span><\/span><\/p>\n

TotalDays         <\/span>: 9.21759837962963E-05<\/span><\/span><\/p>\n

TotalHours        <\/span>: 0.00221222361111111<\/span><\/span><\/p>\n

TotalMinutes      <\/span>: 0.132733416666667<\/span><\/span><\/p>\n

TotalSeconds      <\/span>: 7.964005<\/span><\/span><\/p>\n

TotalMilliseconds : 7964.005<\/span><\/span><\/p>\n<\/blockquote>\n

 <\/span><\/span><\/p>\n

ES, your design decision therefore, boils down to how you anticipate users using your function. If you think they will be pipelining information directly to the function, you may want to consider using the $input<\/b> variable as seen in function add-oneC<\/b>. If storing in an array, and then passing to the function will work for you, then using the foreach<\/i> statement inside the function (as opposed to pipelining the array) would seem to be the better approach. However, in all things, you should test as your performance may vary, as may the performance with different types of data. You should be very careful when making decisions based on mere milliseconds of difference as the Measure-Command<\/b> Windows PowerShell cmdlet really is not that precise (that is why I decided to use 5,000,000 numbers to ensure the commands would take significant time and would therefore make the differences more appreciable). <\/span><\/p>\n

For more information about performance testing of changes to Windows PowerShell scripts, refer to the “<\/span>How can I test the efficacy of my script modifications<\/span><\/a>” Hey, Scripting Guy! blog post. <\/span><\/p>\n

ES, that is all there is to using the Windows PowerShell pipeline. This concludes script design week. Join me tomorrow as I talk about how to work with music files. <\/span><\/p>\n

I invite you to follow me on <\/span>Twitter<\/span><\/a> or <\/span>Facebook<\/span><\/a>. If you have any questions, send email to me at <\/span>scripter@microsoft.com<\/span><\/a> or post them on the <\/span>Official Scripting Guys Forum<\/span><\/a>. See you tomorrow. Until then, peace.<\/span><\/p>\n

 <\/span><\/p>\n

Ed Wilson, Microsoft Scripting Guy<\/span><\/b> <\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Learn how to write Windows PowerShell functions that accept pipelined input.   Hey, Scripting Guy! I really like the way that some Windows PowerShell cmdlets enable me to pipeline things to it. I do not understand why some Windows PowerShell cmdlets do not allow me to pipeline stuff to it, or perhaps I am […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[69,3,4,45],"class_list":["post-16051","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-functions","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Learn how to write Windows PowerShell functions that accept pipelined input.   Hey, Scripting Guy! I really like the way that some Windows PowerShell cmdlets enable me to pipeline things to it. I do not understand why some Windows PowerShell cmdlets do not allow me to pipeline stuff to it, or perhaps I am […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/16051","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=16051"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/16051\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=16051"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=16051"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=16051"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}