If you’ve been reading these posts through sequentially then I have to congratulate you for making it to the end. If you’ve been reading and following along in your own lab then you get a reverse hi-five plus a harlem shake from me because that’s awesome. You’re a dedicated one.
Now check this out… I was trying to think how I would close this series out but I think I’ll do that with Comment-Based help. In my opinion, this is what separates the armatures from the pro’s because it shows you really care that people know how to use your script. You won’t leave them guessing. Trust me – you don’t want to miss this.
In this post we’ll review the comment based help system. Let’s do it!
So I get it: at first comments don’t sound so sexy.
Who cares right?
Well the Comment-Based help system is a little different. Let me show you what I mean…
Comment-Based help
So it’s no surprise that PowerShell support one line comments that start with a pound “#” sign. These are completely ignored.
So let me show you something cool…
In the last script we built it shows you how much freespace is available on a given host. But what happens if you type Get-Help on it? Will anything show up?
Get-Help \.harddrive_data.ps1
Now look at that output – did you see something interesting?
The help put -computerName in brackets meaning the help system knew this was a mandatory parameter.
Why is that? Because we used the [Parameter(Mandatory=$true)] cmdlet option inside the param block of our script.
So check this out: when it comes to Comment-Based help you only need to know these commands:
- .Synopsis
- .Description
- .Parameter
- .Example
That’s it.
Note that each one starts with a dot “.” and the whole thing must be enclosed inside <# and #> tags.
Also there can’t be more than one space after the closing #> tag and the next line in your script.
Let me show you what I’m talking about here..
Open the top of your script and type this in:
<#
.Description
This script returns the hostname and freespace in gigabytes of the C: drive on given computer
.Parameter ComputerName
This is the hostname of the remote computer
.Example
Getting disk information from the local machine
HardDrive_Data -ComputerName localhost
.Example
Getting disk information from a remote host
HardDrive_Data -ComputerName fs01abc1
.Example
Getting disk information from multiple remote hosts
HardDrive_Data -ComputerName fs01abc1, fs01abc2, ws01abc1, dc01abc1
#>
Save the script and then run with with Get-Help
Get-Help .\harddrive_data.ps1 -Full
Looks pretty slick doesn’t it?
When you use the Comment-Based help syntax I showed you earlier – magic happens.
And look at this – we can even see our examples:
Get-Help .\harddrive_data.ps1 -Examples
By the way, you have been wondering why we have to run the scripts with a dot blackslash in front of them. In other words, why do we run scripts by typing:
.\harddrive_data.ps1
instead of
harddrive_data.ps1
The reason happens to deal with security. That dot represents the current directory. So since the file harddrive_data.ps1 is located in the same directory I’m executing the script from I need to put the dot there so it knows the full path to the script.
If I were running it from a different directory such as the C: drive I would change it like so:
C:\harddrive_data.ps1
It’s a security thing because Microsoft wants you to know with zero ambiguity which script you are running. Is it the one you expected or something weird sitting in a weird temp folder?
One other thing I forgot to mention…
When you search the web you might see people putting another dot infront of the script like this:
. .\harddrive_data.ps1
Those two dots separated by a space isn’t a typo. It’s called Dot Sourcing and is a way to maintain access from the console to any variables created inside the script.
Variables created in the script such as $computerName = ‘dc16alx1’ remain in the script. If you go to the console, run the script and then attempt to reassign $computerName to something else it won’t work.
But if you use Dot sourcing it will. It’s just a way to keep in touch with your variables from the console.
Next Steps
There you have it. I hope you liked this tutorial. I strongly suggest you continue learning by playing with scripts and building more of your own to solve problems at your job.
Two sites I like are:
The first one is a classic. There’s no reason why you shouldn’t be here. You can download free eBooks on PowerShell, ask experts in forms for advice and really get plugged into all things PowerShell.
The second one, Poshcode.org is a great place to grab kickass modules and cmdlets. There are tons of free scripts that you can use to add value to your organization.
And finally Nishang is dangerous. It’s dangerous because it’s the post exploitation toolkit of choice for hackers. After gaining a foothold on a computer they’ll often use the weoponized tools in Nishang to completely own a box. I’m putting it here because I want you to know what the bad guys are doing. I want you to be prepared. I’m trusting that you won’t use anything there for malicious intent.
So that’s all for me. If you like this tutorial send me an email or leave a comment. I’m thinking about creating an in-depth video training course on PowerShell in general and on Powershell for Information Security Professionals in particular. Let me know what you think so I can see if this is a valid idea or not.
Thanks for reading and keeping Powershelling!
Connect with Vonnie on Twitter
