Modify PowerShell Comment-Based Help to Display Function Use
Summary: In the final version of my Windows PowerShell WMI helper module, I add aliases and modify comment-based help to find roles of functions.
Microsoft Scripting Guy Ed Wilson here. It is the weekend, at least in Charlotte, North Carolina, in the United States. I have had a lot of fun working on my WMI helper module this week, and the last thing I need to do is to add a few aliases, and add the function description attribute using a technique I recently came up with. Today, I am up to version 6 on my HSGWMIModule module.
Note This is part six of a multipart article on developing a WMI helper module. On Monday, I created the base WMI module, and included a couple of really great functions that query the WMI schema and return WMI class methods and properties. On Tuesday, I added a function that returns the key property of a WMI class. This is useful when working with WMI instance methods. On Wednesday, I created a function that will return the values of those key properties. On Thursday, I added a HasWMIValue filter to the module. Yesterday, I added two functions. The first is a function that will query WMI classes using a wildcard character pattern. The second function is an Out-TempFile function that accepts piped input and displays results in a temporary text file in Notepad.
Another Note The version six of my HSGWMIModule is available on the Scripting Guys Script Repository.
On May 28, 2011, I wrote a Hey, Scripting Guy! Blog post called Learn How to Use Description Attributes in PowerShell Functions in which I talked about using the rather finicky [system.compomentmodel.description] attribute. It does not play well with comment-based help, and it has a tendency to error out for no apparent reason. In that article, I also talk about finding functions that come from various modules, so the article is useful.
On the other hand, I was not extremely happy with the solution. I was playing around looking at the members of a function, and I noticed something—there is a description property; the same property exists for variables, aliases, and other things. The description property of a function appears in the following figure.
The difference is that when creating a new variable with the New-Variable cmdlet or the New-Alias cmdlet, the description parameter is directly exposed. I have not figured out a way to do this for a function—until now. In the same way that I create a function and then add an alias, I can create a function and then add a description to it. The secret is to use the Get-Command cmdlet to return a functioninfo object; from the functioninfo object, I can directly add the description to the function. The command to add a description to a function is shown here:
(Get-Command testfunction).description = “my mred function”
In the following figure, I create a function, and then assign a description to it. Once I have done that, I use the Get-Item cmdlet and pipe the results to the Format-List to display the newly added description.
Okay, enough theory. I want to create aliases for all of the functions exposed by my HSGWMImoduleV5 (I will add the aliases and the function descriptions in HSGWMImoduleV6). The first thing I need to do is find out which functions reside in the module. To do that, I import the module, and then use the Get-Command cmdlet to retrieve the functions. These two commands and their associated output are shown here:
PS C:\Users\ed.IAMMRED> Import-Module hsg*5
PS C:\Users\ed.IAMMRED> Get-Command -Module hsg*5
CommandType Name Definition
Function Get-WmiClassesAndQuery …
Function Get-WMIClassesWithQualifiers …
Function Get-WmiClassMethods …
Function Get-WmiClassProperties …
Function Get-WmiKey …
Function Get-WmiKeyvalue …
Filter HasWmiValue …
Function New-Underline …
Function Out-TempFile begin {…
One thing that makes it easier to add the aliases and the function descriptions is to load the HSGWMImoduleV5 via the Import-Module cmdlet into the Windows PowerShell ISE. This simple action permits me to take advantage of tab expansion, which is a good thing given the length of some of the WMI function names. However, the long names also take advantage of one of my Windows PowerShell best practices of using a descriptive name for the function and shortening the name with an alias.
After the changes are made to the new HSGWMImoduleV6, I save it to my working directory. Next, I remove the HSGWMImoduleV5 from memory by using the Remove-Module cmdlet as shown here:
Remove-Module hsg*
I peruse the function: drive to ensure that all of my WMI functions successfully unloaded. To do this, I use dir command (alias for the Get-Childitem cmdlet) on the function drive. This command is shown here:
dir function:
Now I import my newly revised HSGWMImoduleV6.
I decided to use two fields in comment-based help that are not used by any cmdlets. I found these by examining the results from Get-Help by piping it to Get-Member. This command is shown in the following figure.
By adding the two attributes, I can use Get-Help to filter out my functions. First, I can filter out all of my functions by using Get-Help:
Get-Help * | ? {$_.role}
To find only the functions that work with WMI metadata, I use the value meta in the syntax that is shown here:
Get-Help * | ? {$_.role -match ‘meta’}
To find the helper functions, I use the value helper in the following command:
Get-Help * | ? {$_.role -match ‘helper’}
To find the query commands, I use this query:
Get-Help * | ? {$_.role -match ‘query’}
The commands and associated output are shown in the following figure.
The syntax of one of these comment-based help functions will suffice for you to get the idea. Here are the two new parameters I added to the help:
.Role
Meta
.Component
HSGWMIModuleV6
I placed these beneath the parameter section and above the notes section. This is shown in the following figure.
I created aliases for all the commands in the module. To find all the aliases, use this command:
Get-Command -Module hsg*6 -CommandType function | % {Get-Alias -Definition $_.name}
That’s it for my WMI Helper module. I have uploaded version 6 to the Scripting Guys Script Repository. If there are other things you would like to see in my module, let me know via email at scripter@microsoft.com.
WMI Week will continue tomorrow when I will talk about an easy way to use WMI association classes.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy
Light
Dark
0 comments