Command Based Help Gotcha

I’ve had the chance to play around with some PowerShell scripting again. A nice occasion to try and include some Comment Based Help I read about in TechNet Magazine a couple of months ago. However I couldn’t get it to work in combination with the standard script header template I tend to use for all of my scripts.

I experimented with commenting out each line on its own:

#header
#
#help

or using comment blocks

<#
header
help
#>

even

<#
header
#>
<#
help
#>

and a couple more variations, but no joy. After some “binging” I ended up reading about_Comment_Based_Help;

All of the lines in a comment-based Help topic must be contiguous. If a comment-based Help topic follows a comment that is not part of the Help topic, there must be at least one blank line between the last non-Help comment line and the beginning of the comment-based Help.

It still took some more trial and error to realize that an “empty line” well, needs to be really empty. It cannot contain a comment character either! Call me stupid ;-)

Here’s an example of how it should be done (Ref. line 22):

#========================================================================================================
# AUTHOR
# Koen Vermoesen
# ***.***@***.***
# 2010-05-20
#========================================================================================================
# SCRIPT
# Create custom address lists based on a CSV file
#========================================================================================================
# PREREQUISITES
# /
#========================================================================================================
# CHANGE HISTORY:
# 2010-05-10 Initial version
#========================================================================================================
# TO DO
# /
#========================================================================================================
# COMMENTS
# Parent lists need to proceed child lists in your input csv-file!
#========================================================================================================

#.SYNOPSIS
#Create custom address lists
#
#.DESCRIPTION
#Create custom address lists based on a CSV file called &quot;CreateAddressLists.csv&quot; with these columns
# - Name
# - Container
# - RecipientFilter
#The script will check if the "Container"-field is empty and run de cmdlet with or without "-container" option
#
#.Link
#http://technet.microsoft.com/en-us/library/aa996912.aspx

$Input = "CreateAddressLists.csv"
Import-CSV $Input | Foreach { If ($_.Container -eq "") {New-AddressList -Name $_.Name -RecipientFilter $_.RecipientFilter} else {New-AddressList -Name $_.Name -Container $_.Container -RecipientFilter $_.RecipientFilter}}

For those of you wondering, I have the habit of using scripts not just for bulky or repetitive actions but also as means of documentation and standardization. Additionally these scripts come in handy If you ever need to rebuild some part of the infrastructure. Hence the 35 lines of comment for only 2 lines of code.

http://blog.koenvermoesen.be/about-koen/

Tagged with:
Posted in Scripting
IT Pro Summer GP
IT Pro Summer Grand Prix
MVA
Microsoft Virtual Academy
Pro-Exchange
Pro-Exchange / Pro-Lync / Pro-Office365
MEET

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Join 158 other followers

%d bloggers like this: