Adding help to your custom PowerShell cmdlets: Step-by-step guide

Yesterday, I wrote an article right here at TechGenix through which I defined how you possibly can create your personal custom PowerShell cmdlets. The method entails making a module file after which including capabilities to the module. When correctly constructed, every perform turns into a PowerShell cmdlet. One of many issues that basically differentiates custom cmdlets from these cmdlets which can be native to PowerShell is the absence of any form of help. To point out you what I imply, take a look at what occurs once I use the Get-Help cmdlet to get help with a local PowerShell cmdlet:

PowerShell help
Now check out what occurs once I ask for help with my very own custom cmdlet.

PowerShell help
The absence of any form of help most likely isn’t an enormous deal in case you have created a custom cmdlet purely for self-use. In any case, should you created the cmdlet your self, you presumably know the way it works and don’t want help. If different individuals might finally be utilizing your custom cmdlet, it’s a good suggestion to give them some help. You possibly can present this help in any method that you just like. It’s comparatively widespread to embody the command’s syntax within the command help, however you may embody different issues as effectively. As an illustration, you would possibly embody a tech assist contact or maybe an instance of how the cmdlet is to be used.

PowerShell truly provides you a bit of little bit of steering as to the varieties of help that you just would possibly present. In the event you look again on the earlier screenshot, you’ll discover that the web help is split into a couple of totally different classes, together with Identify, Syntax, Aliases, and Remarks. You possibly can create help messages for any of those classes. Actually, there are even another classes for which you’ll provide help. Appending the -Full parameter to a Get-Help command (Get-Help Get-Service -Full) offers verbose help. As well as to the varieties of issues that you just noticed within the earlier display screen seize, additionally, you will get the complete, unabridged command syntax, which incorporates issues like widespread parameters, inputs, outputs, and extra.

Remark-based help

So let’s go forward and try how to incorporate help right into a custom command. There are literally a couple of other ways to get the job carried out, however I like utilizing a method known as comment-based help as a result of I discover it to be simpler than a number of the different strategies.

Because the identify implies, comment-based help is added to a perform within the type of a remark. This doesn’t imply that you’ve got to learn a cmdlet’s supply code so as to get help. As a substitute, PowerShell shows the help messages in the identical method that you just noticed within the first display screen seize.

This, after all, raises an enormous query. Builders add feedback to PowerShell scripts for any variety of functions. I personally have used feedback to doc a script’s date or model quantity or to remind myself of how a very difficult block of code works. The Get-Help cmdlet doesn’t trigger a majority of these feedback to be displayed, so what’s it that makes comment-based help work?

The trick to utilizing comment-based help is that your help messages have to adhere to a really particular format so as to be acknowledged. The very first thing that you should have to do is to enclose something help associated between a lower than signal and a larger than signal. Additionally, you will want to place a pound signal simply to the fitting of the lower than signal and simply to the left of the larger than signal. Here’s what an empty help based mostly remark part appears like on strains 3 and 4 within the script beneath.

Earlier I identified that the web help was grouped into sections (Identify, Syntax, Alias, and many others.). The important thing to populating these and different sections is to create part headers and part content material throughout the comment-based help part proven within the screenshot above. Once more, this wants to adhere to a really particular format.

Supported part names

The format requires you to use a interval adopted instantly by the identify of the help part that you really want to create. The part identify have to be in all capital letters. Moreover, you can not create custom part names. The supported part names embody:

  • LINK

While you create a help part, you will have to place a interval instantly earlier than the part identify. The part identify have to be adopted by a single clean line. In the event you skip the clean line, the help gained’t work, nor will it work should you use a number of clean strains.

To point out you the way this works, let’s create a Description part and have it to show a short description of what the cmdlet does. Here’s what an outline appears like:

As you may see within the screenshot above, I created a bit header known as .DESCRIPTION. I adopted that header with a clean line after which the textual content that I need the web help to show. On this case, my help textual content solely consumes a single line, however multi-line textual content is allowed.

In the event you take a look at the screenshot beneath, you may see that my description has been added to the Get-Help description for the cmdlet.

PowerShell help
A serving to hand for your custom PowerShell cmdlets

As you may think about, it may be very helpful to add help to the custom PowerShell cmdlets that you just create. That is very true for cmdlets that require parameters to be equipped.

One actually vital factor that you just want to know in regards to the method that I simply confirmed you is that once you add help to a custom cmdlet, your change won’t be mirrored till you save the module file after which shut and reopen PowerShell.

Featured picture: Pixabay

Put up Views:

Extra PowerShell Fundamentals articles

About the Author

Leave a Reply

Your email address will not be published. Required fields are marked *