How to use $PSBoundParameters in PowerShell

Index

• What is this $PSBoundParameters variable?
• Lets take a look.
• How can we apply all this information?
• Splatting parameters
• Summary

What is this $PSBoundParameters variable?

$PSBoundParameters is an automatic variable that contains the parameters passed to a script or function. It only included the parameters and their values that where explicitly supplied by the caller. It is a hashtable wich can therefore be manipulated as such.

Automatic variables in PowerShell are variables that store a particular state. Although you can write to them, it is frowned upon to do so. For more information about automatic variables, check out this link.

Lets take a look

Let’s look at some examples for better understanding how $PSBoundParameters works.

Function Get-PSBoundParameters {
    [CmdletBinding()]
    Param(
        [Parameter()]
        [string]$Param1,
        [Parameter()]
        [string]$Param2
    )

    return $PSBoundParameters
}
****
$params = Get-PSBoundParameters -Param1 'testOne' -Param2 'testTwo'

$params

In the above command, we are executing the function Get-PSBoundParameters, and passing two parameters.

Based on what we know, the result should be a hashtable with the Keys: Param1 and Param2, with the value of those keys being the arguments provided.

Key    Value
---    -----
Param1 testOne
Param2 testTwo

If we now pipe the $params variable to Get-Member we see that we have access to a variaty of methods such as ContainsKey and Add/Remove. ContainsKey can be used to validate if a key (parameter called) exists. And Add/Remove lets you add or remove a key/value pair to/from the hashtable.

How can we apply all this information?

So what can we do with this knowledge? Let me show you with an example function:

Function Test-PSBoundParameters {
    [cmdletbinding()]
    param(
        [Parameter()]
        [string]$Param1,
        [Parameter()]
        [string]$Param2,
        [Parameter()]
        [string]$Param3
    )

    begin {
        #setup our return object
        $result = [PSCustomObject]@{
            TestOne = $false
            TestTwo = $false
        }
    }

    process {
        #use a switch statement to take actions based on passed in parameters
        switch ($PSBoundParameters.Keys) {
            'Param1' {
                #perform actions if ParamOne is used
                $result.TestOne = $true
            }

            'Param2' {
                #perform logic if ParamTwo is used
                $result.TestTwo = $true
            }
            Default {
                Write-Warning "Unhandled parameter -> [$($_)]"
            }
        }
    }

    end {
        return $result
    }
}

If we run Test-PSBoundParameters without parameters we get:

TestOne TestTwo
------- -------
  False   False

Now let’s try again while providing parameters, let run Test-PSBoundParameters -Param1 'value'. This gives us the following result:

TestOne TestTwo
------- -------
   True   False

As you can see the value of TestOne now changed to True.

And if we run Test-PSBoundParameters -Param3 'value' this results in:

WARNING: Unhandled parameter -> [Param3]

TestOne TestTwo
------- -------
  False   False

So the switch statement handles everything correctly wich means our function works.

Splatting parameters

Splatting in PowerShell means taking a hashtable and passing it to a function as parameter/value pairs. To do this you call the function with a hashtable but replace the $ with a @. To demonstrate this we have to update the Get-PSBoundParameters function a little:

Function Get-PSBoundParameters {
    [CmdletBinding()]
    Param(
        [Parameter()]
        [string]$Param1,
        [Parameter()]
        [string]$Param2
    )

    Test-PSBoundParameters @PSBoundParameters
}

If we now run the modified function with parameters like this: Get-PSBoundParameters -Param1 'value' -Param2 'value' the result will look like this:

TestOne TestTwo
------- -------
   True    True

This is because we are splatting $PSBoundParameters in our Get function, causing it to pass matching parameters to our Test function.

See also: about_Splatting

Summary

As we’ve seen, $PSBoundParameters can be usefull depending on what you want to do. Whether you are validating the existance of a parameter, or passing things through with splatting, it helps keep your code nice and clean comparing to the alternatives.