I know a great many people have written about functions and pipelines.  I write to this blog as much for me as I do others. When I write something I learn something new every time.  So with that in mind I’m going to explain how I understand pipe-lining an object to a custom function.

To begin with there are a number of parameter attributes that you can use in ensuring you get the right data for your function.

For the purposes of this Blog we’ll be talking about the following:

[ValueFromPipelineByPropertyName]

My scenario is that I have a closet full of shoes in a PSObject.

Here is what My closet full of shoes looks like:

Now I want to take this set of shoes and print out what they are to the screen. Purpose is to understand what value from pipeline by property name.

Here is the code to build my Closet full of shoes:

$newshoes = @()

$Newshoes += New-Object -TypeName psobject -property (@{‘shoetype’ =’womens’;’shoename’=’highheel’;’description’=’womens high heel shoe in red’})

$Newshoes += New-Object -TypeName psobject -property (@{‘shoetype’ =’mens’;’shoename’=’loafer’;’description’=’leather shoe shaped like a moccasin, with a low flat hee’})

$Newshoes += New-Object -TypeName psobject -property (@{‘shoetype’ =’boys’;’shoename’=’sneaker’;’description’=’soft shoe with a rubber sole worn for sports or casual occasions.’})

$Newshoes += New-Object -TypeName psobject -property (@{‘shoetype’ =’girls’;’shoename’=’Mary Jane’;’description’=’Lime Green Mesh Flower’})

For my single shoe:

$newshoe = new-Object -TypeName psobject -Property (@{‘shoe’=’mens’;’shoename’=’loafer’;’description’=’mens sofa loafer’})

Now on to the function:


function New-Shoes
{
[CmdletBinding()]
param
(
[Parameter( Mandatory=$true,
ParameterSetName='Shoes',
ValueFromPipelineByPropertyName = $true)]
[String[]]
[validateset('Womens','Mens','Boys','Girls')]
[alias("ShoeType")]
$Shoes,

[Parameter( Mandatory=$true,
ValueFromPipelineByPropertyName = $true)]
[String[]]
[alias(‘ShoeName’)]
$Name,

[Parameter( ValueFromPipelineByPropertyName = $true)]
[alias(“Description”)]
[String[]]
$Notes
)

begin
{

}
process
{
write-output “Shoe Gender Type –> $shoes”
write-output “Shoe Name –> $name “
write-output “Description of Shoe –> $notes”
}
end
{
}}

There are a number of ways I can call this function. I can call it via this means:

new-shoes -shoes Womens -name ‘highheel’ -notes ‘womens high heel shoe in red’

I then get back:

Shoe Gender Type –> Womens
Shoe Name –> highheel
Description of Shoe –> womens high heel shoe in red

Or since I have an alias i can do the same command with an alias instead:

new-shoes -shoetype Womens -shoename ‘highheel’ -Description ‘womens high heel shoe in red’

Shoe Gender Type –> Womens
Shoe Name –> highheel
Description of Shoe –> womens high heel shoe in red

Well you are saying that is pretty evident I’ve used that in my functions many times. So What.

Well the cool part is when I have an object that contains members that are the same as the required parameters for my function.  PowerShell will automatically parse them into the variables I need in my function.

My $newShoe variable contains this information:

So now lets see what happens if i send that to my new-shoe function via pipeline.

As you can since i have the keyword [CmdletBinding()] followed by ValueFromPipelineByPropertyName = $true, PowerShell will look at each property name and value in the object passed and put it into the proper parameter in my function.

Since the first Parameter can be either ‘shoes‘ or ‘ShoeType‘ if the object I’m passing has either of these it’ll meet the rules for the first parameter.

[Parameter( Mandatory=$true,
ParameterSetName=’Shoes’,
ValueFromPipelineByPropertyName = $true)]
[String[]]
[validateset(‘Womens’,’Mens’,’Boys’,’Girls’)]
[alias(“ShoeType“)]
$Shoes

The same holds true for each parameter in the parameter block. Now if I take my entire closet of shoes I get the following result:

So because I added [] to my string type PowerShell automatically iterates through each item in my $NewShoes object.

As you can see the [ValueFromPipelineByPropertyName] is pretty handy when it comes to sending an object to your custom function via pipeline.

 

until then Keep Scripting