I had a recent run in with $PSBoundParameters and thought, hey, I should write about that. $PSBoundParameters is an automatic variable. You can read more about it, and others, in Get-Help -Name about_Automatic_Variables, but before you do, let’s chat about it here. This variable contains key-value pairs of the parameters and the corresponding values that are passed to a function, or script. Consider the function declared below.

Function Show-Parameter {
    Param (
        [string]$Text,
        [int]$Number
    )

    $PSBoundParameters
}

Now that we have our function declared, we can invoke it (think, run it), by entering its name.

PS> Show-Parameter
PS> # ^ No parameters and values included,...
PS> # so the function does nothing.
PS> Show-Parameter -Text 'hi'

Key                   Value
---                   -----
Text                  hi

PS> Show-Parameter -Text 'hello' -Number 5

Key                   Value
---                   ----
Text                  hello
Number                5

PS> Show-Parameter -Number 10

Key                   Value
---                   -----
Number                10

It’s important to remember that all our function did was echo the value(s) stored in $PSBoundParameters. Now that we know we can do this, why might we want to do this? In scripting, we often need to make decisions based on information we’ve collected, and in this case, we make our decisions based on whether or not a parameter was used when a function was invoked. Let’s modify the function first and run it a few more times.

Function Show-Parameter {
    Param (
        [string]$Text,
        [int]$Number
    )

    If ($PSBoundParameters.ContainsKey('Text')) {
        Write-Output -InputObject "Text has been included as: '$Text'"
    }

    If ($PSBoundParameters.ContainsKey('Number')) {
        Write-Output -InputObject "Number has been included as: '$Number'"
    }
}

Now our function, when invoked, will take a specific action when a parameter(s) is included. Here’s a few examples.

PS> Show-Parameter -Text 'sample text'
Text has been included as: 'sample text'
PS>
PS> Show-Parameter -Number 20
Number has been included as: '20'
PS>
PS> Show-Parameter -Text 'more sample text' -Number 25
Text has been included as: 'more sample text'
Number has been included as: '25'

Here’s one final modification. In the example below, we’ve removed the -Number parameter and the If statement that checks if that parameter was included. Then, we added a switch statement inside the If statement that checks if the -Text parameter was included. Based on the value provided to the -Text parameter, we’ll take specific actions (up to a point). If the string ‘hello’ is included as the parameter’s value, we’ll reply with one message, if the string ‘hi’ is included as the parameter’s value, we’ll reply with another message, and if anything else is included, we’ll simply reply with the value provided to the parameter.

Function Show-Parameter {
    Param (
        [string]$Text
    )

    If ($PSBoundParameters.ContainsKey('Text')) {
        switch ($Text) {
            {$_ -eq 'hello'} {Write-Output -InputObject 'Hello to you, as well.'; break}
            {$_ -eq 'hi'} {Write-Output -InputObject 'Hi.'; break}
            default {"You entered: $Text"}
        }
    }
}

With $PSBoundParameters, we can check if a parameter is used, as well as, work with the value that’s provided to that parameter. Below are three examples of using the above function.

PS> Show-Parameter -Text hi
Hi.

PS> Show-Parameter -Text hello
Hello to you, as well.

PS> Show-Parameter -Text adios
You entered: adios

That’s it. Enjoy the rest of the weekend and have a great week!