PowerShell makes it possible to create your own custom cmdlets. These are great for automating routine tasks as all systems are unique. Custom cmdlets provide a valuable resource to the budding Administrator who needs to focus on non-routine tasks.
Challenges associated with using custom cmdlets is them lacking help resources. Only minimal help exists for these tools by default. For basic functions it’s not great but you can work with it. That said, almost all functions will have options and multiple scripts can quickly lead to ambiguity and risk to your system. No rule says that you can’t create your own help.
In this article, I want to show you how to make the Get-Help cmdlet work with custom cmdlets. Let’s start first by understanding PowerShell modules.
PowerShell Modules
When you want to create custom cmdlets in PowerShell, you must start by creating a module. A module is essentially just a script file, which can include one or more functions.
Each function is a standalone PowerShell cmdlet that can have it’s own options and help. We’ll discuss this later but first let’s take a look at how to make a module.
Creating a Module
To create a module and a custom PowerShell cmdlet, complete these steps:
- Create one or more PowerShell functions in Notepad.
- Add an Export-ModuleMember command to the script for each function. For example, ‘Export-ModuleMember -Function ‘My-Function’. Here My-Function is the function name.
- Save the file with any name but ensure it has a .PSM1 extension.
- Create a folder at C:\Windows\System32\WindowsPowerShell\v1.0\Modules. The folder name that you’re creating must match the module file name. For example, MyModule.PSM1b, then the folder name would need to be MyModule.
- Now you have made the module you can import it by using the Import-Module cmdlet, followed by the module name.
The image above illustrates a module file. This file contains a single function called Get-MyProcess.
Once the module is present in the system, PowerShell will treat Get-MyProcess as a standalone cmdlet. Let’s now take a look at how you can add help to your new custom cmdlet.
Adding Help to a Custom Cmdlet
When you need help with a PowerShell cmdlet, you can type Get-Help followed by the cmdlet name. If for example, you needed help with the Get-Process cmdlet, you could type Get-Help Get-Process. The command shell would then show you the command syntax. Unfortunately, this doesn’t work for custom cmdlets.
Get-Help provides only basic information for custom PowerShell cmdlets. Yet, you can add extra code to the function that associates it with the cmdlet and make it so that the cmdlet will support Get-Help. If you look back at the first screen capture in this article, you can see that the Get-MyProcess function requires input. Get-Help is useful in this case because it can outline the input type that the cmdlet requires.
Comment Based Help
Adding Get-Help support is also called comment based help. The reason why Microsoft uses the phrase comment based help is that it helps comment organization. Grouping these comments together within a block that begins with <# and ends with #> is needed. The help items must appear after header lines that use a period and a key word in all caps. The supported keywords are:
- SYNOPSIS
- DESCRIPTION
- PARAMETER
- INPUTS
- OUTPUTS
- EXAMPLE
- LINK
- NOTES
- COMPONENT
- ROLE
- FUNCTIONALITY
- FORWARDHELPTARGETNAME
- FORWARDHELPCATEGORY
- REMOTEHELPPRUNESPACE
- EXTERNALHELP
These sections are optional and you can use any combination as you need. If for example, you want to include inputs in the comment based help then it looks like this:
<#
.INPUTS
This is where you would type the input related help information.
#>
Because the help information is a comment, you can enter anything for any keywords you wish to use. That said, Microsoft provides guidance for how you can use various keywords to help you create solutions.
What Went Wrong?
Sometimes you may find that comment based help doesn’t work in the way you would expect. If you have problems getting your comment based help to display correctly, check the following:
- Check keyword spellings and that they’re written in all caps.
- Check you haven’t forgotten the period before the keyword.
- Make sure the keyword is on its own line and nothing is after it.
- Make sure that all keywords and comments fall between the opening and closing markers.
- Check the keyword’s case. Microsoft’s documentation indicates that keywords aren’t case-sensitive. That said, older PowerShell versions only support uppercase keywords. Stick to using uppercase keywords can make life easier.
- Verify no invalid comment based help items are present.
- Try closing and reopening the command shell to clear any data remaining in the cache.
- Enter the Update-Help cmdlet to force the shell to refresh data.
Once you have checked these items, open PowerShell, import the module, and try getting help again. You should see output like the image below, although the actual output will vary based on the file contents.
Final Thoughts
PowerShell allows you to create your own custom cmdlets through using modules. It also only provides extremely basic help for these custom cmdlets by default. That said, you can greatly improve the available help by using comment based help.
Treating your scripts as though you’re preparing them for someone else to run is industrial best practice. This is because you may wish to jump ship at some point or get help from an apprentice gunning for your job. By making their life easier you get better references later on. Obfuscating any process will however negatively impact your career.
FAQs
Under what circumstances might you want to add comment based help to a PowerShell custom cmdlet?
Get-Help support is useful if a PowerShell custom cmdlet requires input parameters. That said, you should add Get-Help support any time someone else uses a custom cmdlet.
If you make a change to comment based help, can you re-import the module without having to stop and re-launch PowerShell?
No, you actually have to terminate the session in order to refresh a module. Doing this dumps content from the cache. This is something you’ll have to remember when creating your module’s content.
What things would you include in an Example PowerShell comment?
The Example section is normally used to provide command examples for users. For instance, you might type the full PowerShell command along with any required parameters. This allows those seeking help to see exactly how the command works.
Can a PowerShell module contain more than one custom cmdlet?
Yes, it’s common for PowerShell modules to include many custom cmdlets. As with many high-level languages you can either run scripts independently or together to achieve a task. This allows you to recycle common functions and processes for different tasks.
Do you need separate Export-ModuleMember PowerShell commands for each function?
Yes you do. If you forget the Export-ModuleMember PowerShell command the custom cmdlet isn’t shown. You’ll see no error message initially as the command shell will skip any faulty code. PowerShell requires this object and its library to execute correctly.
Can the PowerShell help text span multiple lines?
According to Microsoft, the PowerShell help text can span multiple lines. Most high-level languages allow text to fit on multiple lines. This is great for explaining custom cmdlets, options and anything else you need to.
Resources
Microsoft’s PowerShell Documentation
Get Microsoft’s documentation for the Get-Help cmdlet here.
PowerShell Help
Learn more about the help system here.
Writing Help Topics for PowerShell
Discover more about writing comment based help topics here.
PowerShell Modules and Custom Cmdlets
Understand how to build modules and custom cmdlets here.
PowerShell Best Practices
Develop more best practices for scripting here.
Free Resources for PowerShell
Find some great free resources for your scripts here.
The post Adding Get-Help Support to PowerShell Cmdlets appeared first on TechGenix.