Welcome back to the next article in this continuing series on building PowerShell tools for SQL Server management. Hopefully you have gotten good value out of the series so far. If you’ve missed it, you can always check out the previous articles here on SQLServerCentral. Since these articles build on one another, I encourage you to read the previous articles to give you context for this one. This article will take you through how you can easily build help information into your functions that can be used by the standard Powershell help cmdlet, Get-Help.

Comments

The simplest form of help and documentation in any language is comments. In Powershell, we can have either single line or multi-line comments, just like in other languages. Any line starting with a # sign will be considered a comment, like so:

  #Some nice text about the next line saying ‘Hello World!’
  Write-Host -ForegroundColor Cyan ‘Hello World!’

For multi-line comments, we would use <# and #> to encapsulate our comment block, like so:

  <#
  This code is a very simple example, mostly
  to show off multi-line comment blocks.
  Please enjoy!
  #>
Write-Host -ForegroundColor Cyan ‘You should really read the comments.’

How we use comments differs for each person writing code, but I highly encourage you to use some comments. You never know when the next person will come along and read your code.  Trying to decipher code in this manner can be a real struggle. 

Comment Based Help

The thing about Powershell is that it tries to give us a leg up when documenting our code. New users and veterans alike should be familiar with using Get-Help to explore and discover new functionality. It would be pretty nice if we could provide the same kind of help file for our own tools and functions, right?

This sort of question is often considered “leading the witness”, because you can, and it is pretty easy. Powershell supports Comment Based Help, which you can find out more about by using Get-Help about_Comment_Based_Help. The general idea is if we use a specific syntax for writing our comments, we can build a nice help file without a lot of extra work.

The format is straightforward. We will use a multi-line comment block with some keywords within the function. Using this pattern will let Get-Help interpret the block into a useful output. The block must be placed in one of three locations relative to the function:

• At the beginning of the function.
• At the end of the function.
• Immediately before the Function keyword.

Personally, I like putting the comment block at the beginning before I declare my parameter block.

Let’s take a look at an example. We’re going to revisit the Test-SqlConnection we used for the previous article, but this time add some comments to it. Let’s just look at the comment block we’ll add:

  <#
.SYNOPSIS
Tests if a SQL Server is available.
.DESCRIPTION
This function will test to see if a SQL Server is available for query connections. The
process to test this is by executing a simple T-SQL statement via Invoke-SqlCmd against
a passed instance name. If the query returns successfully, it will display the instance
name and the tempdb creation date. If the connection fails, only the instance name will
be displayed and the tempdb creation date will be null.
.PARAMETER Instances
String array of instance names to be tested
.EXAMPLE
Test-SQLConnection -Instances @('PICARD','RIKER')
#>

We can see how this block get formatted, by putting the keyword with a dot (i.e., ‘.SYNOPSIS’) on a line, then what we want within that section following it. All that remains is to load our function and call Get-Help against it:

  Get-Help Test-SqlConnection -Full

This returns the help we've added to our script, as you can see in the image below.

What is nice is that not only will Get-Help use what we’ve input about the function via the comments, but it will also add additional information based on what it can figure out from the function code, such as syntax and parameter definitions.

Self Documentation

I’ve always contended that code is not finished until it has been documented. Powershell tries to help out with this through the Comment Based Help, giving script authors a way to fold their own comments into the existing help system. Not only does it make things easy, it keeps the help experience consistent for others who might use your tools. This is crucial, because in addition to these benefits, now if someone wants to use these functions they do not have to open the script itself to understand how it should be used.

We now understand how to build robust functions and document how they should be used by ourselves and others. What’s next is to cover how functions interact with each other. Powershell is built on the idea that we create discrete components that work together to accomplish larger tasks. To do this, we need consider the inputs and outputs of our tools as we build them. Join me next month as we discuss this important aspect.

Article Resources:

• GitHub Repository: https://github.com/MikeFal/PowershellToolbox-SSC
• Test-SqlConnection: https://github.com/MikeFal/PowershellToolbox-SSC/blob/master/Test-SqlConnection.ps1
• SSC-SQLToolBox: https://github.com/MikeFal/PowershellToolbox-SSC/blob/master/SSC-SQLToolBox.ps1