Thursday, March 29, 2018

PS template - Splatted update snippet

3/29/2018: Over the years of working with Powershell for quick admin work, I've become a sizable fan of splatting powershell commands.

First a 'Splat' Introduction:


For folks late to the party, "splatting' leverages standard hashtables to encapsulate 'sets' of parameters for commandlets. The short form is that you take all the parameters you'll be feeding to a given commandlet, configure them by matching name->value combos into a hash varable, and then, by specifying the hash variable with an 'at' (@) prefix rather than dollar-sign ($), Powershell & the commandlet interpret your splatted hash table as the set of parameters with which to execute your desired command.

Quick, very simple case in point.
Say you want to grant permissions to an Exchange Online mailbox:

With traditional Powershell, you'd do something like the following:

add-mailboxpermission -Identity=$($ombx.samaccountname) -User=$($Grantee) -AccessRights="FullAccess" -whatif ; 

To convert the above to a Splatted command, you'd build your hashtable with each parameter name & value combo specified:

    Identity=$($ombx.samaccountname) ;
    User=$($Grantee) ;
    AccessRights="FullAccess" ;
    whatif=$($whatif) ;

You'll note I'm using a splatted variable for the -whatif parameter as well.
Any parameter of the commandlet - including -whatif & -confirm - can be included in the splat. And as switch parameters, you simple indicate their state by using $true or $false.

So, now that you have your splat variable constructed with the parameters, you can run the same Exchange Online Management shell cmdlet, specifying that you're 'splatting' the hash to be used as the commandlet's parameters, by specifying it as @spltMbxGrant (rather than $spltMbxGrant).

And in this case, since I have the -whatif param spec'd in $spltMbxGrant, I can control the value of the underlying $whatif variable, by assigning the value $true/$false, right at the top:

$whatif=$true ; 
add-exomailboxpermission @spltMbxGrant ;

If I change that leading $whatif=$true, the command will execute a '-whatif' pass (exactly as if I'd specified the -whatif parameter on the commandline). 

And if I then rerun the same block of code with $whatif=$false, it will execute the actual production change in permissions.

But why do all this?  

Well, for me, one of the big benefits I like about using a splat, is that it lets me 'demo' & dump exactly what parameters I'm going to use, right into the console (into a transcript in most cases). And then I can roll back the 'whatif' pass, and run it again intact 'hot'.

So I can take the above, and expand it a bit, to make it:
  1. Echo the details -- what I have spec'd for the command to be executed.
  2. Set -whatif $true and test-fire exactly the command I plan to run.
  3. Then live-fire the full command.
  4. And finally, I can even recycle the values from my original splat, to run a get-xxx commandlet to dump back the results of the change.
Like so:

No comments:

Post a Comment