When you begin to learn Windows PowerShell, you'll soon find yourself neck-deep in objects. Objects are one of the fundamental concepts of what makes PowerShell so user-friendly—and powerful at the same time.<\/p>\n
As you dive deeper into the language, the next concept that you'll typically stumble over is the pipeline. So let's take your PowerShell skills to the next level by incorporating pipeline input abilities into your advanced functions!<\/p>\n
The pipeline is what makes PowerShell so unique. The thought of a pipeline is not new. We've been able to pipe strings from the output of one command to the input of another command for a long time. However, it wasn't until PowerShell came along that we had a language that allowed us to pipe objects from one command to another.<\/p>\n
The following is a very basic advanced function called Get-Something<\/b> with a single parameter called $item<\/b>. When called, this function simply outputs a sentence to the console that states whatever value of $item<\/b> is passed to the function:<\/p>\n
Function Get-Something {<\/p>\n
[CmdletBinding()]<\/p>\n
Param($item)<\/p>\n
Write-Host "You passed the parameter $item into the function"<\/p>\n
}<\/p>\n
For a function to accept pipeline input, it needs to be an advanced function. Maybe that's all it needs. I hope!<\/p>\n
Nope. Not only did the $item<\/b> parameter not have a value, but I also got an error message about some input object that cannot be bound to something. I suppose making a function advanced isn't quite the whole story for here. Fear not. The journey required to get us where we need to go is a short one. Read on…<\/p>\n To get the value abc123<\/b> to represent the $item<\/b> variable in our function, PowerShell has to know how to match the value to the $item<\/b> parameter. This is done through a process called parameter binding. Parameter binding is the selection process that goes on whenever an advanced function or a compiled cmdlet sees something coming from the pipeline. During this process, it tries to match which parameter (the only one in our case) to bind to our abc123<\/b> value.<\/p>\n To set up the function for this parameter binding process, I need to smarten the $item<\/b> parameter a bit by using the Parameter<\/b> keyword instead of simply throwing $item<\/b> in between the Param<\/b> parentheses. This allows me to add parameter attributes to the $item<\/b> parameter. Among those are two attributes directly related to accepting pipeline input: ValueFromPipeline<\/b> and ValueFromPipelineByPropertyName<\/b>.<\/p>\n This will make the function look something like this:<\/p>\n Function Get-Something {<\/p>\n [CmdletBinding()]<\/p>\n Param(<\/p>\n [Parameter()]<\/p>\n $item<\/p>\n )<\/p>\n Write-Host "You passed the parameter $item into the function"<\/p>\n }<\/p>\n When the Parameter<\/b> keyword is representing $item<\/b>, there is a spot to place the first parameter attribute called ValueFromPipeline<\/b>:<\/p>\n Function Get-Something {<\/p>\n [CmdletBinding()]<\/p>\n Param(<\/p>\n [Parameter(ValueFromPipeline)]<\/p>\n $item<\/p>\n )<\/p>\n Write-Host "You passed the parameter $item into the function"<\/p>\n }<\/p>\n The ValueFromPipeline<\/b> keyword finally allows passing the abc123<\/b> value directly to the Get-Something<\/b> function:<\/p>\n PS> 'abc123' | Get-Something<\/p>\n PS> You passed the parameter abc123 into the function<\/p>\n This is great! But maybe I want to pass Windows service names to my function and output their names in the sentence:<\/p>\n PS> Get-Service | Get-Something<\/p>\n PS> You passed the parameter System.ServiceProcess.ServiceController into the function<\/p>\n Huh? I was expecting it to look something like this with each service represented by $item<\/b>:<\/p>\n You passed the parameter Application Identity into the function<\/p>\n You passed the parameter DHCP Client into the function<\/p>\n You passed the parameter DNS Client into the function<\/p>\n Sorry. Work is never done, right? We need to add a little bit more code.<\/p>\n The reason this happens is because the ValueFromPipeline<\/b> keyword binds entire objects to the parameter. The service name is simply a property of the object type System.ServiceProcess.ServiceController.<\/p>\n When I piped abc123<\/b> to Get-Something<\/b>, that was a simple string. Get-Service<\/b> is sending a more complicated object to the function now and Get-Something<\/b> doesn't know how to handle it. I need a way to bind only a single property of the System.ServiceProcess.ServiceController objects that Get-Service<\/b> outputs.<\/p>\n To do this, I can't use ValueFromPipeline<\/b>. Instead, I need to use a similar (yet way too long keyword) called ValueFromPipelineByPropertyName<\/b> in its place:<\/p>\n Function Get-Something {<\/p>\n [CmdletBinding()]<\/p>\n Param(<\/p>\n [Parameter(ValueFromPipelineByPropertyName)]<\/p>\n $item<\/p>\n )<\/p>\n Write-Host "You passed the parameter $item into the function"<\/p>\n }<\/p>\n However, if you leave the function as-is and try to pipe Get-Service<\/b> directly to Get-Something<\/b>, you'll soon be in for a lot of nasty, red error text.<\/p>\n Why? Because PowerShell still doesn't know how to bind those objects from Get-Service<\/b> to the function. I need to change the parameter's name to match the object property I'd like to accept input from. In this case, each System.ServiceProcess.ServiceController object that Get-Service<\/b> outputs has a Name<\/b> property that I'd like to show up in the sentence output.<\/p>\n Let's change the parameter name to $Name<\/b> and see what happens:<\/p>\n Function Get-Something {<\/p>\n [CmdletBinding()]<\/p>\n Param(<\/p>\n [Parameter(ValueFromPipelineByPropertyName)]<\/p>\n $Name<\/p>\n )<\/p>\n Write-Host "You passed the parameter $Name into the function"<\/p>\n }<\/p>\n PS> Get-Service | Get-Something<\/p>\n PS> You passed the parameter mylastservice into the function<\/p>\n Odd. It only output the Windows service "mylastservice." Why not all of them?<\/p>\n It's because, by default, it will only output the very last object in the pipeline. To process each object output by Get-Service<\/b>, I need to include the Write-Host<\/b> line in a process block.<\/p>\n Any code inside a process block is run for each object coming from the pipeline—not only the last one. To process all objects, I'll add one of these process blocks inside of the function:<\/p>\n Function Get-Something {<\/p>\n [CmdletBinding()]<\/p>\n Param(<\/p>\n [Parameter(ValueFromPipelineByPropertyName)]<\/p>\n $Name<\/p>\n )<\/p>\n process {<\/p>\n Write-Host "You passed the parameter $Name into the function"<\/p>\n }<\/p>\n }<\/p>\n PS> Get-Service | Get-Something<\/p>\n PS> You passed the parameter service1 into the function<\/p>\n PS> You passed the parameter service2 into the function<\/p>\n PS> You passed the parameter service3 into the function<\/p>\n PS> You passed the parameter service4 into the function<\/p>\n Much better! You can now see that the name of each service is being successfully passed into the sentence string and being output to the console by Write-Host<\/b>. You now have a function that you can pass objects or object properties to.<\/p>\n If you got some value from this information and would like to dive deeper into PowerShell, the pipeline, advanced functions, and modules, be sure to check out my Pluralsight course about building advanced PowerShell functions and modules. I'll take you into a way deep dive about advanced functions and modules.<\/p>\n ~Adam<\/p>\n Thank you very much for these two awesome posts, Adam. Join me tomorrow for more cool Windows PowerShell stuff. <\/p>\n I invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n Ed Wilson, Microsoft Scripting Guy<\/b> <\/p>\n","protected":false},"excerpt":{"rendered":" Summary: Microsoft MVP, Adam Bertram, talks about accepting pipelined input into Windows PowerShell advanced functions. Microsoft Scripting Guy, Ed Wilson, is here. Today Microsoft MVP, Adam Bertram, returns to talk about accepting pipeline input into advanced Windows PowerShell functions. Note This is the second post in a series. Don’t miss Introduction to Advanced PowerShell Functions. When […]<\/p>\n","protected":false},"author":597,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-76271","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting"],"acf":[],"blog_post_summary":" Summary: Microsoft MVP, Adam Bertram, talks about accepting pipelined input into Windows PowerShell advanced functions. Microsoft Scripting Guy, Ed Wilson, is here. Today Microsoft MVP, Adam Bertram, returns to talk about accepting pipeline input into advanced Windows PowerShell functions. Note This is the second post in a series. Don’t miss Introduction to Advanced PowerShell Functions. When […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/76271","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\/597"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=76271"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/76271\/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=76271"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=76271"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=76271"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/p1.png\" "\\"Image")
<\/a><\/p>\n![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/3755.p2.png\" "\\"Image")
<\/a><\/p>\n![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/p3.png\" "\\"Image")
<\/a><\/p>\n