PowerShell Splatting

Howdy all,Splat

Welcome to my first post on Inframon’s new WordPress blog. I plan to write a series of blogs around PowerShell and all things cool and scripty. If anyone has any particular topics they want me to blog, I am open to suggestions.  If you have any questions after reading this, then do not hesitate to drop me a line. All my details can be found on the corporate directory. So without any further ado let’s crack on.

Today I will be covering PowerShell parameter splatting. Firstly, what is it? Then how does it work and finally finishing off with a real life example of where splatting can be really useful. There will be some lengthy texts to read through but I will finish off with some examples for you to work through and understand.

What is splatting?

To put it very simply, splatting is a way to pass parameter values of a cmdlet as a unit. This will not only make your scripting look neater and easier to read, but will also make your scripts look a lot more professional. I personally hate seeing scripts that have multiple parameters, so many that the code goes off the screen and I have to use a scroll bar to navigate back and forth. I equally hate seeing the back tick (`) used to put a long line of code over multiple lines. A common mistake of the back tick is the belief that is solely used for carriage returns.

Splatted parameters are stored in variables just like normal, standard parameters. The main difference with splatted parameters is, when called, they begin with the @ symbol rather than the $ symbol. This special @ symbol tells PowerShell you are passing a collection of values instead of a single value.

Ways to Splat

There are 2 ways to splat in PowerShell, via a hash table or via an array. A Hash Table is used when parameter names are needed, and an array when dealing with positional parameters. For example, we could use a Hash table when using a cmdlet which has parameters and an array when passing a lengthy select-object statement.

Examples

Splatting syntax;

<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>

Splatting with a hash table

Let’s take a simple command like Get-ChildItem to demonstrate. Using a traditional PowerShell method the command would similar to the following;

get-childitem -Path "C:\demo" -Filter *.txt -Recurse -ErrorAction SilentlyContinue

This example has 3 command specific parameters and 1 common parameter. If we were to refactor this code, making use of splatting a hash table, it would look like this;

#Create the hash table
$ChildItemHash = @{
     Path = "C:\Demo"
     Filter = "*.txt"
     Recurse = $true
     Erroraction = "SilentlyContinue"
                  }
#call the cmd and splat the hash table
Get-ChildItem @ChildItemHash

Whilst not a very good real life example it shows the potential of making your scripts neater by splatting.

Splatting with an array

Continuing our use of the Get-Child item command we may wish to have a lengthy Select-Object statement like the following;

get-childitem -Path "C:\demo" -Filter *.txt -Recurse -ErrorAction SilentlyContinue | Select-Object Mode, LastWriteTime, @{N="Size(Bytes)";E={$_.Length}}, Fullname

This select statement has 5 different positional parameters which we can very easily refactor by splatting an array. By splatting the above command, it will become this; (remember when splatting with an array we use the $ symbol.)

$SelectArray = @(
    "Mode", "LastWriteTime",
    @{N="Size(Bytes)";E={$_.Length}},
    "Fullname"
               )
get-childitem -Path "C:\demo" -Filter *.txt -Recurse -ErrorAction SilentlyContinue | Select-Object $SelectArray

Real life example

A common real life example is the creation of creating AD accounts using the New-ADUser cmdlet. This cmdlet takes many parameters and can soon become lengthy, ugly and take over ones screen.  For example;

New-ADUser -Name "Adam Coxon" -GivenName "Adam" -Surname "Coxon" -SamAccountName "Adam.Coxon" -Company "Inframon" -UserPrincipalName "Adam.coxon@inframon.com" -Path "OU=Swindon,DC=test,DC=local"

The number of parameters in the above example may not even come close to what is required inside a typical customers corporate Active Directory. This example can be very nicely refactored by using a simple hash table, like so;

$ADUserParams = @{
    Name = "Adam Coxon"
    GivenName = "Adam"
    Surname = "Coxon"
    SamAccountName = "Adam.Coxon"
    Company = "Inframon"
    UserPrincipalName = "Adam.coxon@inframon.com"
    Path = "OU=Swindon,DC=test,DC=local"
                 }
New-ADUser @ADUserParams

This looks far neater and is a lot easier to read all the parameters.

Summary

I hope this short blog post has quickly highlighted and demonstrated the potential of using splatting inside your scripts. There are times when splatting can really help and other times when it may not be necessary. You may also choose to only splat certain parameters and leave others outside.  I have seen issues in the past where PowerShell doesn’t like splatting credential objects. Ultimately the choose is yours.

Happy splatting to all.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.