PowerShell Splatting
Splatting passes a hashtable of parameters to a command using @ instead of $. Build the hashtable with keys named after the parameters, then call the command with @params.
Documentation: Microsoft Learn
Overview
It earns its place in two situations. The first is a call with so many parameters that the line becomes unreadable, where splatting turns it into a block you can scan and comment. The second is conditional parameters: you cannot easily add -Credential to a command only sometimes, but you can add a key to a hashtable inside an if statement, which is the clean way to express optional arguments.
The sigil is the whole trick. $params is the hashtable itself. @params tells PowerShell to unpack it into parameters. Writing $params passes one hashtable as a single positional argument, which is a confusing error rather than an obvious one.
An array can be splatted too, for positional arguments, but the hashtable form is what you will use.
Inspect this example’s structure
Read the command and its supplied arguments. This example requires real PowerShell or its module; this diagram does not execute it.
$params = @{
Name = 'W*'
ErrorAction = 'SilentlyContinue'
}
Get-Service @params | Select-Object -First 4 Name, Status- Stage 1$params
Positional values or no named parameters - Stage 2Select-Object
-First
An example to inspect
Preview the example. Sign in for the full lesson and activities.
$params = @{
Name = 'W*'
ErrorAction = 'SilentlyContinue'
}
Get-Service @params | Select-Object -First 4 Name, StatusWhat happens
The hashtable holds two keys matching two real parameters of Get-Service. The call unpacks them with @params, so it behaves exactly as if you had typed -Name 'W*' -ErrorAction SilentlyContinue. Extra parameters can still be added inline alongside a splat, which is why the pipeline to Select-Object works normally.
Worth remembering
- Hashtable keys must match parameter names.
- Call with @params, not $params.
- Add keys conditionally to make parameters optional.
- You can mix a splat with inline parameters in the same call.
Primary documentation
Try it
Illustrative output · values vary by environment
Example reader
Inspect this page's example
Run supported commands against the practice data, or inspect the example without executing it.
Ready to inspect.
Passes two parameters from a hashtable using @ instead of $.
Show reference output
Illustrative output · values vary by environment
Name Status ---- ------ W32Time Running WinDefend Running WinRM Running wuauserv Stopped