Modify PowerShell Comment-Based Help to Display Function Use

Modify PowerShell Comment-Based Help to Display Function Use

  • Comments 1
  • Likes

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.

Image of description property of a function

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.

Image of creating function and assigning 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.

Image of piping Get-Help results to Get-Member

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.

Image of commands and associated output

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.

Image of two new parameters beneath parameter section

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

 

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hi Ed,

    a brilliant idea!

    This is a nice add-on to the already excellent comment based help system!

    We can take all unused properties and (mis)use them for our own purposes!

    Hopefully the future versions of powershell will not make use of it ...

    Klaus.