ScriptRunner Blog
Parameter Binding concepts in PowerShell
Table of Contents
![Post Featured Image](https://www.scriptrunner.com/hubfs/Imported_Blog_Media/blogarticle-parameter-binding-1.png)
Parameter binding is a fundamental concept in PowerShell. And you can end up scratching your head for a while if you do not understand this concept fully, as I recently experienced first-hand.
In my case it was a simple re-read of advanced functions and then trying a simple script to make a calculator, in order to re-test how much I can recall. The problem started when I tried to supply parameter values from the pipeline. In this blog post I will be going over two fundamental PowerShell pipeline parameter binding concepts: “byValue” and “byProperty”.
Let us examine my first attempt at my calculator program. As you can see below it is a simple PowerShell script to add, subtract, multiply and divide two numbers (Figure 1a + 1b).
![Screenshot: Calculator script. Name of Function: Get-Calculation; Three Parameters: firstNumber, secondNumber and Operator](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog1-857x315-1.png?width=857&height=315&name=Blog1-857x315-1.png)
Figure 1a: Simple Calculator Part 1. Name of Function: Get-Calculation; Three Parameters: $firstNumber, $secondNumber and $operator. Parameter Attributes: Mandatory and Accept value from Pipeline. The operator parameter has a fixed set of values.
![Screenshot: Calculator script. Defining the output object and writing the output into the pipeline](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog2-857x355-1.png?width=857&height=355&name=Blog2-857x355-1.png)
Figure 1b: Simple Calculator Part 2. Defining the output object and writing the output object into the pipeline.
Here is where the problem starts: when I try to create a custom object with properties same as my function parameters and pass it to Get-Calculation function in the pipeline, it gives me an error (Figure 3).
![Screenshot: Passing a custom PS Object to Get-Calculation](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog3-857x320-1.png?width=857&height=320&name=Blog3-857x320-1.png)
Figure 3: Passing a custom PS Object to Get-Calculation
Troubleshooting with Trace-Command
![Screenshot: Using Trace-Command to examine parameter binding](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog4-857x251-1.png?width=857&height=251&name=Blog4-857x251-1.png)
Figure 4: Using Trace-Command to examine parameter binding
We can observe in figure 5 that instead of binding object properties to parameter the “whole” object ($myObj) is supplied as value to the parameter.
![Screenshot: Parameter binding](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog5-857x449-1.png?width=857&height=449&name=Blog5-857x449-1.png)
Figure 5: Parameter binding
Parameter Binding: byValue vs. byProperty
“Bind by Value” means that the incoming object will be supplied as value to the parameter. The Pipeline will not process the object and bind specific properties of the object to parameters for the next cmdlet/function in the pipeline. If we observe the output from Trace-Command, the pipeline is trying to bind our object ({firstNumber=1; secondNumber=4; operator=+}) to the parameter “firstNumber” and so on.
The solution is to bind “byProperty”. In our example we need to explicitly tell the pipeline to bind the incoming object’s properties to our parameter. As shown below we changed our original script to bind byProperty (Figure 6).
![Screenshot: Parameter attribute to accept value by propert](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog6-857x315-1.png?width=857&height=315&name=Blog6-857x315-1.png)
Figure 6: Parameter attribute to accept value by property
Next, we again observe the behavior using Trace-Command. As we can see this time, object properties are bound to our parameters correctly (Figure 7). However, there is one catch: in order for this to work the incoming object’s properties should have the same names as the function parameters.
![Screenshot: Trace-Command reveals, parameter binding is successful](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog7-857x306-1.png?width=857&height=306&name=Blog7-857x306-1.png)
Figure 7: Parameter binding is successful
Test: Parameter Binding byValue and byProperty
![Screenshot: Accepting parameter byValue and byProperty](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog8-857x262-1.png?width=857&height=262&name=Blog8-857x262-1.png)
Figure 8: Accepting parameter byValue and byProperty
Now our function accepts parameter values using both the byValue and byProperty option. Let’s take a simple example where we send two object one of type Int (Figure 9) and the other a custom PS object (Figure 10).
![Screenshot: Supplying two objects to Get-Valculation](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog9-857x346-1.png?width=857&height=346&name=Blog9-857x346-1.png)
Figure 9: Supplying two objects to Get-Calculation
The first result where we got 8 might be a bit confusing but the program worked as expected for second object (In case you’re wondering out operator property, I will leave it as an homework for you).
We are going to observe binding using our good old friend the Trace-command. As you can observe in Figure 10 the first object, number 4 of type Int is bind to firstNumber and secondNumber resulting in sum being 8. This demonstrates that the pipeline will plug in the same object to all the parameters which are accepting value from the pipeline if we are using “byValue” option.
![Screenshot: Parameter binding for Int object](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog10-857x242-1.png?width=857&height=242&name=Blog10-857x242-1.png)
Figure 10: Parameter binding for Int object
In the case of our PS custom object, we can observe that the pipeline first tries to bind byValue but it fails and then, as expected, switches to byProperty option and starts binding parameter by property name (Figure 11).
![Screenshot: Parameter binding for PS custom object](https://www.scriptrunner.com/hs-fs/hubfs/Imported_Blog_Media/Blog11-857x438-1.png?width=857&height=438&name=Blog11-857x438-1.png)
Figure 11: Parameter binding for PS custom object
Conclusion
Here are some key takeaways from this post:
- Default option for parameter binding is to bind by value.
- If we have selected both byValue and byProperty option, the pipeline will start by binding using byValue option.
- If the parameters are supplied directly to the function, then the process block is executed exactly once.
- If the parameters are supplied by pipeline, the process block is executed once for each object in the pipeline.
I hope this post would help you to further understand and implement advanced functions correctly.
Related Content
Related posts
14 min read
Privacy Management with PowerShell – Let's look at the core features of Priva!
Jul 16, 2024 by Damian Scoles
All you need to know about Privacy Management, privacy management policies, rules, and subject rights requests.
Why...
4 min read
Let's celebrate System Administrator Appreciation Day!
Jul 3, 2024 by Matthias Jütte
Every last Friday of July, we get to celebrate System Administrator Appreciation Day, a special day dedicated to...
8 min read
PowerShell 7: What are the pros and cons of switching from Windows PowerShell 5.1?
Jul 2, 2024 by Philip Lorenz
Windows PowerShell 5.1 is usually preinstalled and the default – is it worth switching to PowerShell 7, or will it lead...
About the author:
Sonny is a self-proclaimed PowerShell preacher who lives in the beautiful city of Halifax on the east coast of Canada. Sonny has worked in Cybersecurity for more than 10 years and has acted as the primary technical lead and subject matter expert on many Cyber Security Assessments for various private and public organizations. Sonny regularly speaks at various security conferences such as BSides, AtlSecCon, ISACA, OWASP etc.
Latest posts:
- Privacy Management with PowerShell – Let's look at the core features of Priva!
- Let's celebrate System Administrator Appreciation Day!
- PowerShell 7: What are the pros and cons of switching from Windows PowerShell 5.1?
- Azure Arc & integration in VMware vSphere
- PowerShell Secrets – Bulletproof password management