My function template

The Story

I’ve been writing PowerShell scripts and functions for quite some time now. It all started with simple tasks that had to be done. The requirement was – it should work. The more complex they were, the more troublesome was debugging. Imagine one master script including several others for up to 2000 lines of code in total. All scripts loaded in PowerShell ISE with debugging traps set at some points. Then run and step into, one line after another. Looking at variables, hunting down that pesky issue. Long were those nights. PowerShell V2 times let me add.

The pipelines

Then I began to write functions. Simple at first, advanced later on. The code was split into smaller chunks. It was easier to maintain and debug if needed. At this point as my functions relied one on another, default output should be kept clean only for passing objects. Bye bye Write-Host. Bye bye Write-Output “I did this and that”. Fortunately there is more than just one pipeline in PowerShell. Want to know more? Just update your help in PowerShell and search for about_pipelines

(Remember to run those in a PoSh as Administrator)

Also here’s some good reading about this:

Write-Verbose, Write-Warning, Write-Error are really great if I want to output some additional information during my function execution. And the best part is – they do not pollute the output.

There are number of ways one can write a function.

  • Type everything by hand
  • In ISE press CTRL + J and select Cmdlet (advanced function) or Cmdlet (advanced function) – complete

  • Copy from existing functions and delete what is not needed
  • Use a template

I’d like to show you my template I’m using for simple, yet very verbose functions. The idea is stolen from Mike F Robbins (w | github) and adjusted a little bit.

Get-FunctionTemplate

This is a scaffolding for every new function I’m creating. I’ll just copy the content to a new file and I’m ready to go.

This creates a pipeline-ready function with Begin, Process and End blocks. It accepts one string parameter ComputerName which can be also a collection of strings. It goes through each one of them in Process block and… does nothing 🙂

That was… astonishing, right? The important things here are those Write-Verbose messages. Let’s take a look at the output they generate. Let’s add some verbosity then:

Way better. As you can see there is a bunch of information about my environment – username, computer name I’m running, whether I’m running as Administrator, version of my PowerShell and runtime, etc.

Tips

Write-Verbose messages are using timestamps and are formatted in a way that nicely alignes on the screen.

I also use brackets {} to surround any variable. This way if an empty one is passed I’ll notice that right away (take a look at second ‘Processing computer { }’ message.

Get-FunctionTemplateV5

Since Windows PowerShell v5 we also have access to Information stream. That is why I’ve also built a template for functions used in V5 and above:

Not only I can further split the information into different streams, but I can also tag them if Write-Information is used.

To see information stream, parameter -InformationAction must be set to Continue.

The true magic starts when variables are being utilized. Here I’m assigning everything from information stream to MyInformation variable. Remember not to use $ here.

And if you need only specific tagged information then, a simple query:

Why is this helpful? I’m not the only one using my code. If the tool user has any problems – I’ll just ask him to run with InformationVariable and pass me the information. Trust me, nearly 80% of “YOUR CODE IS NOT WORKING” are just PEBCAKs (Problem Exists Between Chair And Keyboard) problems.

Summary

Using these templates allows me to quickly create new functions with prepared scaffoldings so I don’t need to type those by hand. It is also usefull when others try to build functions. It creates standarization. Created functions are using output stream only for passing objects, while still being talkative in Verbose, Debug, Error or Information streams.

Both these functions can be found on my GitHub in ArcAdminTools module.

You can also install the module directly from PowerShell Gallery:

If you have any comments – feel free to contact me.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s