PowerShell Splatting Tricks

If you’ve never heard of splatting in PowerShell or possibly read about it but never used it, you should probably consider it.  Briefly, splatting is the ability to package up parameters into a hashtable and use the hashtable to supply the parameters to a function call. The parameters which are passed into a function automatically populate a hashtable called $PSBoundParameters. Note that to “splat” a hashtable you use an @ in place of the normal $. So to pass $PSBoundParameters, you’d use @PSBoundParameters. If this isn’t making sense, please refer to the code example below.

Why would you want to do this? I can think of a couple of instances where the functionality is very useful.

First, consider a function which calls several other, related functions. If the parameters for the “inner” are the same (or similar), splatting can make the resulting function calls very easy.

For example, assume we have a functions which start and stop a “widget” (with some options, of course). In order write a restart-widget function, we can simply pass the $PSBoundParameters hashtable on to the start/stop functions.
The code could look something like this:

function start-item{
      #start the item using the provided options
function stop-item{
      #Stop the item using the provided options
function restart-item{
      #restart the item using the provided options
      #note, the hashtable with parameters passed to this function is called $PSBoundParameters
      stop-item @PSBoundParameters
      start-item @PSBoundParameters

Note that with 3 switch parameters, you’d have to write 8 different if/then branches to pass the appropriate switches to these functions without using splatting.

Another example of splatting is when writing a proxy function, you will often be adding or removing parameters from a given function and you will need to adjust the hashtable accordingly before passing it into the “wrapped” function.

The first several times I used splatting, I was simply passing $PSBoundParameters to a subordinate function. In many cases, though, you’ll be constructing your own hashtable or modifying $PSBoundParameters in order to supply parameters to another function.

A couple of corner-cases which I haven’t ever seen discussed are:

  1. How are switch parameters handled in a hashtable since there isn’t really a value?
  2. Can I mix splatting with normal parameter passing

To answer these questions, we’ll write a simple function (all best-practices are out the window) and try it out.

function show-splat{
  $PSBoundParameters | out-string
    write-host "Hello!"
  write-host $name

Calling it as such gives us the answers:

PS C:\> $parms=@{hello=$true}
PS C:\> show-splat -name Mike @parms
Key Value
--- -----
name Mike
hello True


We see clearly that the switch ($hello) is simply passed as a boolean value, and we were able to mix a named parameter (-name) with splatting.  Mixing the two could be useful if you had a lengthy command-line and wanted to specify options for it using splatting or if you only wanted to pass a selection of parameters on to another function.


Anyway, splatting is a powerful technique which can easily simplify your functions.  Let me know if you have situations where it seems appropriate.