What's PowerShell Splatting?

PowerShell splatting may sound strange, but this technique offers a convenient way to format and send arguments to cmdlets and functions. Instead of a long list of parameters or those same parameters separated by error-prone backticks, you can leverage splatting to make your code more readable and easier to use.

Splatting is a method of passing a collection of parameter values to a command as a unit. PowerShell associates each value in the collection with a command parameter.

Prerequisites

If you’d like to follow along with this article, ensure you have Windows PowerShell 5.1 for most of the common functionality but PowerShell 7.1 to be able to override splatted parameters (demo below).

What is PowerShell Splatting?

To understand PowerShell splatting, you must first understand basic parameters. Typically, when you pass parameters to a command in PowerShell, you’d use a dash, the parameter name followed by the argument as shown below.

Copy-Item -Path "TestFile.txt" -Destination "CopiedFile.txt" -WhatIf -Force

Alternatively, you could pass parameters using backticks as well.

Copy-Item `
	-Path "TestFile.txt" `
	-Destination "CopiedFile.txt" `
	-WhatIf `
	-Force

Why might you use the traditional method or the backtick method? The traditional method is fine, but with many parameters, this often becomes unwieldy to deal with and read. Using a backtick, “`, appears to give much better readability. This technique is usually not recommended due to the ease of forgetting or misplacing a backtick.

Instead, you can use PowerShell splatting. Splatted parameter values are stored in named splatting variables, which look like standard variables, but begin with an At symbol (@) instead of a dollar sign ($). The At symbol tells PowerShell that you are passing a collection of values, instead of a single value.

For example, you can create a hashtable called $Params and then pass that set of parameters defined in the hashtable to the Copy-Item cmdlet as shown below.

$Params = @{
  "Path"        = "TestFile.txt"
  "Destination" = "CopiedFile.txt"
  "WhatIf"      = $True
  "Force"       = $True
}

Copy-Item @Params

Combining Traditional Parameters and Splatting

When you are testing scripts, or on the command-line, you can easily combine both methods. With scripts, it is often best to ultimately create a splatted variable to assign to the function or cmdlet. As an example of what this looks like is below:

$Params = @{
  "Path"        = "TestFile.txt"
  "Destination" = "CopiedFile.txt"
}

Copy-Item @Params -Force -WhatIf

As you can tell, this is a pretty useful technique where you don’t have to give up either method depending on your needs. Sometimes you may want to test an additional parameter or format the parameters differently for formatting by combining methods.

Overriding Splatted Parameters

In PowerShell 7.1, you can now override splatted parameters. Prior to this, you could not modify a splatted parameter via a passed parameter. As an example of overriding splatted parameters, notice how the -WhatIf parameter is overridden below.

$Params = @{
  "Path"        = "TestFile.txt"
  "Destination" = "CopiedFile.txt"
  "WhatIf"      = $True
  "Force"       = $True
}

Copy-Item @Params -WhatIf:$False

Overriding splatted parameters allows you to negate the key/value parameter defined in the hashtable and instead, use the value of the parameter defined traditionally.

Splatting with hash tables

Use a hash table to splat parameter name and value pairs. You can use this format for all parameter types, including positional and switch parameters. Positional parameters must be assigned by name.

The following examples compare two Copy-Item commands that copy the Test.txt file to the Test2.txt file in the same directory. The first example uses the traditional format in which parameter names are included.

Copy-Item -Path "test.txt" -Destination "test2.txt"

The second example uses hash table splatting.

$HashArguments = @{
  Path = "test.txt"
  Destination = "test2.txt"
}
Copy-Item @HashArguments

The first command creates a hash table of parameter-name and parameter-value pairs and stores it in the $HashArguments variable. The second command uses the $HashArguments variable in a command with splatting. The At symbol (@HashArguments) replaces the dollar sign ($HashArguments) in the command.

Note Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in PowerShell is: @{=; =; ...}

Splatting with arrays

Use an array to splat values for positional parameters, which do not require parameter names. The values must be in position-number order in the array.

The following examples compare two Copy-Item commands that copy the Test.txt file to the Test2.txt file in the same directory. The first example uses the traditional format in which parameter names are omitted. The parameter values appear in position order in the command.

Copy-Item "test.txt" "test2.txt"

The second example uses array splatting. The first command creates an array of the parameter values and stores it in the $ArrayArguments variable. The values are in position order in the array. The second command uses the $ArrayArguments variable in a command in splatting. The At symbol (@ArrayArguments) replaces the dollar sign ($ArrayArguments) in the command.

$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments

Examples

Reuse splatted parameters in different commands

To change the colors of all commands, just change the value of the $Colors variable.

The first command creates a hash table of parameter names and values and stores the hash table in the $Colors variable.

$Colors = @{
  ForegroundColor = "black"; 
  BackgroundColor = "white"
}

The second and third commands use the $Colors variable for splatting in a Write-Host command. To use the $Colors variable, replace the dollar sign ($Colors) with an At symbol (@Colors).

#Write a message with the colors in $Colors
Write-Host "This is a test." @Colors

#Write second message with same colors. The position of splatted
#hash table does not matter.
Write-Host @Colors "This is another test."

Conclusion

Splatting parameters to functions and cmdlets is an extremely useful technique for code readability and functionality. As it’s easy to manipulate hashtables and arrays, you can quickly expand upon splatted values to conditionally modify values depending on options that were passed. Incorporate this powerful technique into your scripts today!

Not a reader? Watch this related video tutorial:

5/5 - (1 vote)