{"id":87168,"date":"2020-05-13T18:44:48","date_gmt":"2020-05-13T18:44:48","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=87168"},"modified":"2021-08-24T13:39:11","modified_gmt":"2021-08-24T13:39:11","slug":"how-to-add-help-to-powershell-scripts","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/sysadmin\/powershell\/how-to-add-help-to-powershell-scripts\/","title":{"rendered":"How to Add Help to PowerShell Scripts"},"content":{"rendered":"

Shortly after writing my last article on Parameters<\/a>, I had to update a script, and I wanted to make it easier for others to run. One of the features I wanted to add was the ability to show them what the script would do with the provided parameters without actually running the script, in other words, provide \u201chelp\u201d.<\/p>\n

Using a Switch to Control Help<\/h2>\n

My initial thought was to add another parameter, make it a Boolean and then check the state of it. If it\u2019s true, display some help text. If not, run the code. However, like many things, the creators of PowerShell thought of a solution that\u2019s even easier that I\u2019ll get to later.<\/p>\n

To keep things simple, I\u2019ll start with the na\u00efve example. (note I\u2019ve started using Visual Studio Code to develop my PowerShell and but also still use the deprecated PowerShell ISE IDE, so my examples may come from either.)<\/p>\n

Save this script as Boolean_help.ps1<\/em>.<\/p>\n

param([boolean]\u00a0$help\u00a0)\r\n#\r\n#\u00a0Author:\u00a0Greg\u00a0D.\u00a0Moore\r\n#\u00a0Date:\u00a02020-02-18\r\n#\u00a0Version:\u00a01.0\r\n#\u00a0Show\u00a0boolean\u00a0help\r\n#\r\nif\u00a0($help\u00a0-eq\u00a0$true)\r\n{\r\n\u00a0\u00a0\u00a0\u00a0write-host\u00a0\"This\u00a0is\u00a0help\u00a0for\u00a0this\u00a0program.\u00a0It\u00a0does\u00a0nothing.\u00a0Hope\u00a0that\u00a0helps.\"\r\n}\r\nelse\r\n{\r\n\u00a0\u00a0\u00a0\u00a0write-host\u00a0\"Do\u00a0nothing.\"\r\n}<\/pre>\n
To run it, simply navigate to the folder where it\u2019s saved and execute it.<\/p>\n
.\\Boolean_help.ps1<\/pre>\n
Since you haven\u2019t supplied a value for the $help<\/code> parameter, your output should be:<\/p>\n
<\/p>\n
If you add a $true<\/code> value as follows, you will see your help message.<\/p>\n
.\\Boolean_help.ps1 $true<\/pre>\n
Here are the results.<\/p>\n
<\/p>\n
That\u2019s a step in the right direction, but it\u2019s not quite good enough. What if your next user who isn\u2019t overly PowerShell savvy tries to use it and does something like the following or other variations?<\/p>\n
.\\Boolean_help.ps1 -help true<\/pre>\n
<\/p>\n
Your user may get frustrated trying to get help from your script. Fortunately, PowerShell provides a different and, in my opinion, a far superior way of handling certain conditionals, and that\u2019s with a data type known as switch<\/code>.<\/p>\n
Enter the following script and save it as Switch_help.ps1<\/em>.<\/p>\n
param([switch]\u00a0$help\u00a0)\r\n#\r\n#\u00a0Author:\u00a0Greg\u00a0D.\u00a0Moore\r\n#\u00a0Date:\u00a02020-02-18\r\n#\u00a0Version:\u00a01.0\r\n#\u00a0Show\u00a0switch\u00a0help\r\n#\r\nif\u00a0($help)\r\n{\r\n\u00a0\u00a0\u00a0\u00a0write-host\u00a0\"This\u00a0is\u00a0help\u00a0for\u00a0this\u00a0program.\u00a0It\u00a0does\u00a0nothing.\u00a0Hope\u00a0that\u00a0helps.\"\r\n}\r\nelse\r\n{\r\n\u00a0\u00a0\u00a0\u00a0write-host\u00a0\"Do\u00a0nothing.\"\r\n}<\/pre>\n
Here, instead of defining $help<\/code> as a Boolean<\/code>, it is now a switch<\/code> datatype. The switch<\/code> acts similar to a Boolean<\/code>, but not quite.<\/p>\n
Run the following, and you will see what I mean.<\/p>\n
.\\Switch_help.ps1\r\n.\\Switch_help.ps1 -help\r\n.\\Switch_help.ps1 -help help\r\n.\\Switch_help.ps1 -help help 1\r\n.\\Switch_help.ps1 -help help $false<\/pre>\n
As you can see, it doesn\u2019t really matter what value you put after the \u2013help<\/code> parameter. As long as the parameter itself is referenced when the script is called, it will have the value of $true<\/code>.<\/p>\n
<\/p>\n
It should also be clear that the switch<\/code> datatype isn\u2019t limited to just help. You can use it for enabling or disabling other items. For example, you might want to have a parameter called $debug<\/code>, which would allow you to enable debug information. This is a great place for the use of the switch parameter.<\/p>\n
However, you may already realize that the help provided above isn\u2019t in the format that most cmdlets provide. I will come back to that later in this article, but first, take a look at some other options with parameters that will help those who run your code.<\/p>\n
Adding Default Parameters<\/h2>\n
I don\u2019t know about you, but if I can, I like to make it harder to make mistakes. One way of doing that is to provide a fixed set of default parameters. For example, you might have a script that can only run against a fixed set of servers.<\/p>\n
Enter the following script and save it as Defaults.ps1<\/em>.<\/p>\n
param([parameter(mandatory)]\u00a0[validateset(\"ProdDB_Server\",\"DevDB_Server\")]\u00a0[string]\u00a0$dbserver\u00a0)\r\nwrite-host\u00a0\"You\u00a0picked\u00a0$dbserver!\"<\/pre>\n
Now, I have to take a slight detour and mention one limitation of Visual Code Studio for development is that, at the time of this writing, I have not found a way to have it automatically pop-up parameters and possible defaults. For the following example, I recommend using the PowerShell ISE to see how this can work. If you enter the script name and the parameter \u2013dbserver<\/code> and then space, you should see a small pop-up<\/p>\n
.\\Defaults.ps1 -dbserver<\/pre>\n
<\/p>\n
If you select one of those two items, the script will run as you expect.<\/p>\n
Obviously, if you add another server, for example, a UAT server, you\u2019d have to update the script. But, by using validated parameters, you ideally avoid a user from entering an invalid server name here.<\/p>\n
Also, if you do try to type in an option not allowed, you will get an error message.<\/p>\n
.\\Defaults.ps1 -dbserver UATDBserver<\/pre>\n
<\/p>\n
Conflicting Defaults<\/h2>\n
If you start to use default parameters, you may suddenly find yourself with required parameters that conflict with each other. For example, if you are using scripts to deploy code (and if you\u2019re not, you should be) you might find in some cases you want to deploy to an environment, but other times to a specific database.<\/p>\n
Now, you could write a script that takes both mandatory parameters and then tries to figure out what you want, but there\u2019s an easier way. Enter the following:<\/p>\n
param([parameter(mandatory, ParameterSetName='ByEnvironment')] [validateset(\"ProdDB_Server\",\"DevDB_Server\")] [string] $dbserver, \r\n[parameter(mandatory, ParameterSetName='ByDatabase')] [validateset(\"sales\",\"product\")] [string] $database ) \r\nif ($dbserver)\r\n{\r\n    Write-Host \"Your code will be deployed to the $dbserver server\"\r\n}\r\nif ($database)\r\n{\r\n    Write-Host \"Your code will be deployed to the $database database\"\r\n} <\/pre>\n
And save it as Conflicting_Parameters.ps1.<\/em><\/p>\n
When you try to run it, you will find you can decide whether you want to deploy to a specific server using the $dbserver<\/code> parameter OR to a specific database using the $database<\/code> parameter. For example, you may want to initially want to deploy a new script to your dev server, and once tested to your production server, or, in the second case, you may want to deploy the script to a specific database across all your servers at once.<\/p>\n
.\\Conflicting_Parameters.ps1 -database product\r\n.\\Conflicting_Parameters.ps1 -dbserver DevDB_Server<\/pre>\n
<\/p>\n
Save the following script as Conflicting_Parameters_2.ps1<\/em>:<\/p>\n
param([parameter(mandatory, ParameterSetName='ByEnvironment')] [validateset(\"ProdDB_Server\",\"DevDB_Server\")] [string] $dbserver, \r\n[parameter(mandatory, ParameterSetName='ByDatabase')] [validateset(\"sales\",\"product\")] [string] $database, \r\n[parameter(mandatory, ParameterSetName='ByEnvironment')] [validateset(\"Europe\",\"North America\",\"All\")] [string] $region,\r\n[string] $comment) \r\nif ($dbserver)\r\n{    \r\n    Write-Host \"Your code will be deployed to the $dbserver server in the $region region.\"\r\n}\r\nif ($database)\r\n{\r\n    Write-Host \"Your code will be deployed to the $database database\"\r\n}\r\nif ($comment)\r\n{\r\n    Write-host \"Your comment was: $comment\"\r\n} <\/pre>\n
You will note several major changes. You now have two parameters, $dbserver<\/code> and $region<\/code> that are both part of the same Parameter Set ByEnvironment<\/code>. Note that they\u2019re separated by the $database<\/code> parameter. This should make it clear, that the ParameterSetName<\/code> is what ties them together, not their placement in the list of parameters. Also, you will note that there is a final optional parameter, $comment<\/code> that is not tied to either Parameter Set.<\/p>\n
<\/p>\n
The $comment<\/code> parameter can be optionally used with either Parameter Set.<\/p>\n
Adding Better Help<\/h2>\n
As noted above, the first and most obvious solutions for providing help that come to mind are the ones mentioned at the start of the article. However, like most things, PowerShell provides a better way of handling this.<\/p>\n
First, your scripts already might give help if parameters. Simply try this:<\/p>\n
get-help .\\Conflicting_Parameters_2.ps1  <\/pre>\n
You should see:<\/p>\n
<\/p>\n
So that\u2019s a start.<\/p>\n
But it might be nice to actually let users know what the parameters, like \u2013region<\/code>, mean.<\/p>\n
Take the script Conflicting_Parameters_2.ps1<\/em> and save it as Conflicting_Parameters_Help1.ps1<\/em>.<\/p>\n
Then add the following block of code as the first lines of the script:<\/p>\n
<#\r\n.Description\r\nThis is a test file to demonstrate conflicting parameters.\r\n#> <\/pre>\n
Save this and then run:<\/p>\n
get-help .\\Conflict_Parameters_Help1.ps1 <\/pre>\n
You should see something very similar to:<\/p>\n
<\/p>\n
Now, this is starting to look a bit more like a real script!<\/p>\n
But you haven\u2019t solved the problem of giving useful examples about what the parameters can or should be. Fortunately, that\u2019s easy to fix with the addition of the following lines. Add these and save as Conflicting_Parameters_Help2.ps1.<\/em><\/p>\n
.PARAMETER dbserver\r\nDetermines if you are deploying to the Production or Dev DB server. Valid values are ProdDB_Server or DevDB_Server\r\nMust be used with the region parameter. May not be used with the database parameter\r\n\r\n.PARAMETER database\r\nDetermines if you are deploying to the Sales or Product database. Valid values are sales or product\r\nMay not be used with the dbServer and region parameters\r\n\r\n.PARAMETER region\r\nDetermines which region you are deploying to. Valid values are Europe, North America or All\r\nMust be used with the dbserver parameter. May not be used with the database parameter\r\n\r\n.PARAMETER Comment \r\nAllows you to add a comment to your deploy.<\/pre>\n
Make sure to have a blank line before the first .PARAMETER<\/code> and after the final line of the block above.<\/p>\n
If you simply run this:<\/p>\n
get-help .\\Conflict_Parameters_Help2.ps1 <\/pre>\n
You won\u2019t see any difference. However, if you run this code:<\/p>\n
get-help .\\Conflicting_Parameters_Help2.ps1 -Full <\/pre>\n
You will now see all your parameter help in its full glory! I\u2019ve only reproduced the relevant part here with details highlighted<\/p>\n
<\/p>\n
Note that the details about the parameters are now part of the help. You will also note that common parameters are also listed.<\/p>\n
While this help text is useful, you may find yourself wanting it in a separate window so you can consult it while continue writing your script. In this case, try the following:<\/p>\n
get-help .\\Conflicting_Parameters_Help2.ps1 -showwindow <\/pre>\n
You should see a window similar to this:<\/p>\n
<\/p>\n
Note that the examples nicely highlight the parameters and because there are two Parameter Sets, shows you both possibilities.<\/p>\n
However, you may ask yourself, what if you want help on just one parameter? PowerShell allows for that also:<\/p>\n
Run this code:<\/p>\n
get-help .\\Conflicting_Parameters_Help2.ps1 -Parameter dbserver <\/pre>\n
You should get:<\/p>\n
<\/p>\n
You will also notice, in addition to the help details you\u2019ve provided, PowerShell is also informing the user if the parameter is required, if it is handled by position and other details. In an earlier article, I discussed the value of naming parameters<\/a>. I will cover pipeline input at a later date.<\/p>\n
If you want to make life even easier for your users, you may want to include examples of how to execute the script with the proper parameters.<\/p>\n
Add the following lines (again, remembering to have a blank line before and after the new lines) and save as Conflicting_Parameters_Help3.ps1.<\/em><\/p>\n
.EXAMPLE\r\nPS> .\\Conflicting_Parameters_Help3 -dbserver ProdDB_Server -region 'North America' -Comment 'deployment by server and region example!'\r\n.EXAMPLE\r\nPS> .\\Conflicting_Parameters_Help3 -database Sales -Comment 'deployment by database example!'\r\n.SYNOPSIS\r\nUsed to determine where files should be deployed. <\/pre>\n
 <\/p>\n
Then run the following:<\/p>\n
get-help .\\Conflicting_Parameters_Help3.ps1 -Examples <\/pre>\n
You will get back something very much like:<\/p>\n
<\/p>\n
If you cut and paste either example, it will run the command as expected. For example, using the first example will return:<\/p>\n
<\/p>\n
Finally, I want to show you another way of adding help. It\u2019s not one I would generally recommend but in some cases may be quicker and easier. For ease of coding, I\u2019ll put the entire script here. It\u2019s basically the last script with two minor modifications. Save it as Conflicting_Parameters_Help4.ps1.<\/em><\/p>\n
<#\r\n.Description\r\nThis is a test file to demonstrate conflicting parameters.\r\n.PARAMETER database\r\nDetermines if you are deploying to the Sales or Product database. Valid values are sales or product\r\nMay not be used with the dbServer and region parameters\r\n.PARAMETER region\r\nDetermines which region you are deploying to. Valid values are Europe, North America or All\r\nMust be used with the dbserver parameter. May not be used with the database parameter\r\n.PARAMETER Comment\r\nAllows you to add a comment to your deploy.\r\n.EXAMPLE\r\nPS> .\\Conflicting_Parameters_Help3 -dbserver ProdDB_Server -region 'North America' -Comment 'deployment by server and region example!'\r\n.EXAMPLE\r\nPS> .\\Conflicting_Parameters_Help3 -database Sales -Comment 'deployment by database example!'\r\n.SYNOPSIS\r\nUsed to determine where files should be deployed.\r\n#>\r\nparam([parameter(mandatory, ParameterSetName='ByEnvironment')] [validateset(\"ProdDB_Server\",\"DevDB_Server\")] # Determines if you are deploying to the Production or Dev DB server. Valid values are ProdDB_Server or DevDB_Server Must be used with the region parameter. May not be used with the database parameter \r\n[string] $dbserver, \r\n[parameter(mandatory, ParameterSetName='ByDatabase')] [validateset(\"sales\",\"product\")] [string] $database, \r\n[parameter(mandatory, ParameterSetName='ByEnvironment')] [validateset(\"Europe\",\"North America\",\"All\")] [string] $region,\r\n[string] $comment) \r\nif ($dbserver)\r\n{    \r\n    Write-Host \"Your code will be deployed to the $dbserver server in the $region region.\"\r\n}\r\nif ($database)\r\n{\r\n    Write-Host \"Your code will be deployed to the $database database\"\r\n}\r\nif ($comment)\r\n{\r\n    Write-host \"Your comment was: $comment\"\r\n}<\/pre>\n
 <\/p>\n
What you will notice is that I\u2019ve removed the .PARAMETER<\/code> help message for dbserver<\/code> and moved it directly into the parameter definition.<\/p>\n
As above, run this:<\/p>\n
get-help .\\Conflicting_Parameters_Help4.ps1 -Parameter dbserver <\/pre>\n
You should get:<\/p>\n
<\/p>\n
The advantage of writing parameter help this way is that the help can be entered as you\u2019re creating the parameter. However, I find it a bit harder to read this way. There\u2019s also an additional issue. If you take Conflicting_Parameters_Help4.ps1<\/em> and add the following lines to the help comment and save it as Conflicting_Parameters_Help5.ps1<\/em>.<\/p>\n
.PARAMETER dbserver\r\nHelp here overrides what's in the parameter definition. <\/pre>\n
Then run it.<\/p>\n
get-help .\\Conflicting_Parameters_Help5.ps1 -Parameter dbserver <\/pre>\n
You will get:<\/p>\n
<\/p>\n
While it can be handy to add the help message directly to the parameter definition, if you later go back and add a full comment-based help block, that will take precedence.<\/p>\n
For the details on what you can add to your help block, I would recommend you read the Microsoft help for full details located here<\/a>.<\/p>\n
Conclusion<\/h2>\n
Hopefully, this article has helped you understand how to switch to better parameters and how to enable your users by adding a real PowerShell help to your scripts. As always, the scripts are available on GitHub<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
PowerShell scripts are the tool of choice for many admins, but how do you make them easy for others to use? In this article, Greg Moore shows how to add professional looking help to your scripts that work just like the help in cmdlets. …<\/p>\n","protected":false},"author":319367,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[143527,53,35],"tags":[95505],"coauthors":[61343],"class_list":["post-87168","post","type-post","status-publish","format-standard","hentry","category-database-administration-sql-server","category-featured","category-powershell","tag-compliant-database-devops"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/87168","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/319367"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=87168"}],"version-history":[{"count":5,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/87168\/revisions"}],"predecessor-version":[{"id":87190,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/87168\/revisions\/87190"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=87168"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=87168"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=87168"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=87168"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}