4 min read
How to Leverage IT Automation for Maximum Efficiency
Are you ready for a transformation of your IT operations? Our brand-new white paper, Maximizing IT Automation: The...
Surely you already use comments within your PowerShell scripts, and surely you too have been annoyed by uncommented scripts.
Comments in PowerShell scripts make it possible to document certain processes directly in the code. You can also add extra notes to code snippets. For example, this is useful if you want to extend a function with more features.
But beyond just information, comments in PowerShell can help create articles about your functions when used correctly. In this article, I’ll show you how to use meta-data to get script information via Get-Help.
Comment-Based Help Keywords
The magic word for our project is Comment-Based Help.
As the name suggests, this method allows us to generate help information through powershell comment. These comments have to be arranged and formatted correctly – you’ll find out exactly how in this section.
In principle, we can distinguish between two types: Comment-Based Help for Functions and for Scripts. The former goes one layer deeper and starts with functions, which we want to provide with meta-data. However, if your code is not prepared in functions, it is also possible to provide a whole script with this information.
Before we look at their exact usage, I list all keywords for the Comment-Based Help here:
| KEYWORD | FUNCTION |
| SYNOPSIS | Short description of the script or function |
| DESCRIPTION | Detailed description of the code |
| PARAMETER | Description of a used parameter. Keyword is used several times (1x per parameter). The parameter must be named additionally after the keyword! |
| INPUTS | Description of possible objects that can be passed into the function via a pipeline. |
| OUTPUTS | Output values of the function |
| NOTES | Additional information about the code |
| LINK | URL to the corresponding online help (if available) |
In order not to go beyond the scope of this article, I will limit the listing to the keywords that are used most often. You can find more keywords in the Microsoft Docs.
Note: Script header information also plays an important role for the use of scripts in the ScriptRunner software platform. You can read more about it here: PowerShell Script Headers and Parameters for use in ScriptRunner.
Using Comment-Based Help
The keywords listed above are notated in a specific format in the code. This looks like the following:
Notation of Help Keywords and Content in the PowerShell Script Header
The keywords are headed with a period – the corresponding text is placed below the keyword. The keyword block is commented out using “<##>”.
Comment-Based Scripts and Functions differ in the sense that the Comment block is placed differently. For functions, it is best to place the block under the function name. You can also put the block right in front of the function. This can be done without a blank line. Another option is to place it at the end of the function body.
To include information in scripts, place the PowerShell Comment block at the start of the code. This block should contain details about the entire script, not just parts of it.
Example and Usage of Comment-Based Help
In this section, we will show how to use Comment-Based Help. We will demonstrate this with a function.
This function will list all directory and file objects in a specific directory. It will also limit the results to a certain hierarchy depth.
PowerShell already provides this functionality – the following example only serves for understanding.
Example function
The goal now is to explain how things work. We will use descriptions, examples, and parameter information in a help article.
Meta-data in the function header
In this code a holistic help comment has now been written. On a Get-Help call on this information, we now get the following output in the console:
Output from Get-Help Get-ChildItemDepth
The -Examples parameter can also be used to output all available examples:
Output of the examples stored in the script
Tip: For more examples of scripts built according to PowerShell best practices, take a look at our ScriptRunner ActionPacks.
Conclusion
In principle, it can be said that Comment-Based Help offers great benefits for IT departments using PowerShell scripts. You can easily see the self-built functions. This way, your colleagues won’t have to sift through many lines of code to understand how they work.
Due to its limited length, the script name can only ever give a rough indication of a script’s function without being able to go into detailed information. This way of creating help also saves the need for external documentation of the code.
If there is a basic policy or code-of-conduct that explicitly requires the use of these help sections, I can strongly recommend the Pester module. It can be configured to check the code for the presence of help articles before each release. You can even check if every single parameter has a description.
Related Links
Related posts
About the author:
Latest posts:
- How to Leverage IT Automation for Maximum Efficiency
- Automate VMware vSphere: Boost efficiency with PowerCLI
- Streamline data governance with PowerShell: What is Microsoft Purview for you?
- Mastering PowerShell PSDefaultParameterValues for Streamlined Automation
- Mastering PowerShell Loops: Techniques for Streamlining Your Scripts