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