Powershell

Within Powershell there is a very powerful and yet simple to use feature.  The ability to place helpful information and documentation within your scripts and functions.

You’ve already seen the results of it in use.  When you type in HELP and a CMDLET

HELP GET-CHILDITEM

Which usually reveals this typical screen.

image

So you can leverage the HELP system when YOU make scripts too!  It’s call “Comment Based Help”.  If you type

HELP about-Comment-Based-Help

You’ll get some well written instructions from Microsoft.

So here is a sample Powershell Script that does nothing other than do a “Hello World” to the console

————-

OUT-HOST ‘Hello World’

———–

Now if we save this file as HELLOWORLD.PS1 and try doing HELP HELLOWORLD.PS1 all we’ll get is a single line that says

HELLOWORLD.PS1

To put some help into this just drop in a “Comment Block” with appropriate keywords (documented in the Help files) to fill in the “HELP” Details

A comment block begins with a

<#

and ends with a

#>

For example we have various keywords such as

.SYNOPSIS
.DESCRIPTION
.EXAMPLE
.NOTES
.LINK

There are others, but we’ll add in these to our file so you can see you could add in the HELP

—— HELLOWORLD.PS1 ———

<#

.SYNOPSIS
This is a Powershell Script – It is simple

.DESCRIPTION
The Script you have when run will produce Output on the Console that says
Hello World.  It will do nothing else.  It will not sing, or do pretty lights, it will
not break anything.  All it will do is print TWO WORDS on the screen.  And only
the words ‘Hello World’.  I know, it is a lame script.  I am sorry.

.EXAMPLE
./HELLOWORLD.PS1

Output on Screen
Hello World

.NOTES
I would love to have some really impressive notes in this field, but since the
script is so lame the only Notes I can put in are
Pick up some Milk
A loaf of Bread
A box of cookies

.LINK
http://www.energizedtech.com

#>

WRITE-HOST ‘Hello World’

—— HELLOWORLD.PS1 ———

Now when you type in HELP ./HELLOWORLD.PS1 you’ll get THIS output

image

And yes, it does support the standard extensions to HELP like –full, –detailed and –examples .  You won’t see the .NOTES from Help until you do a

HELP ./HELLOWORLD.PS1 –full

Afterwards you’ll see this and the Website link I dropped in for further “help” 🙂

image

It’s not required to do this, but it does add a huge level of professionalism to your scripts and even makes it easier for Subordinates to know that anytime they’re in Powershell just type HELP and a Cmdlet or function to “GET-HELP”

Powershell, It is Easy

Sean
The Energized Tech