{"id":12251,"date":"2011-10-29T00:01:00","date_gmt":"2011-10-29T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/10\/29\/modify-powershell-comment-based-help-to-display-function-use\/"},"modified":"2011-10-29T00:01:00","modified_gmt":"2011-10-29T00:01:00","slug":"modify-powershell-comment-based-help-to-display-function-use","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/modify-powershell-comment-based-help-to-display-function-use\/","title":{"rendered":"Modify PowerShell Comment-Based Help to Display Function Use"},"content":{"rendered":"

Summary:<\/strong> In the final version of my Windows PowerShell WMI helper module, I add aliases and modify comment-based help to find roles of functions.<\/span><\/span><\/p>\n<\/p>\n

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<\/b> attribute using a technique I recently came up with. Today, I am up to version 6 on my HSGWMIModule<\/b> module. <\/span><\/p>\n

\n

Note<\/b> This is part six of a multipart article on developing a WMI helper module. On <\/span><\/span>Monday<\/span><\/a>, 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 <\/span>Tuesday<\/span><\/a>, I added a function that returns the key property of a WMI class. This is useful when working with WMI instance methods. On <\/span>Wednesday<\/span><\/a>, I created a function that will return the values of those key properties. On <\/span>Thursday<\/span><\/a>, I added a HasWMIValue<\/b> filter to the module. Yesterday<\/a>, 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<\/b> function that accepts piped input and displays results in a temporary text file in Notepad. <\/span><\/span><\/p>\n

Another Note<\/b> The version six of my HSGWMIModule<\/b> is available on the <\/span><\/span>Scripting Guys Script Repository<\/span><\/a>.<\/span><\/span><\/p>\n<\/blockquote>\n

On May 28, 2011, I wrote a Hey, Scripting Guy! Blog post called <\/span>Learn How to Use Description Attributes in PowerShell Functions<\/span><\/a> <\/i>in which I talked about using the rather finicky [system.compomentmodel.description]<\/b> 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. <\/span><\/span><\/span><\/p>\n

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<\/b> property; the same property exists for variables, aliases, and other things. The description<\/b> property of a function appears in the following figure.<\/span><\/p>\n

\"Image<\/a><\/span><\/p>\n

The difference is that when creating a new variable with the New-Variable<\/b> cmdlet or the New-Alias<\/b> cmdlet, the description <\/i>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<\/b> cmdlet to return a functioninfo<\/b> object; from the functioninfo<\/b> <\/i>object, I can directly add the description to the function. The command to add a description to a function is shown here:<\/span><\/p>\n

\n

(Get-Command testfunction).description = “my mred function”<\/span><\/p>\n<\/blockquote>\n

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<\/b> cmdlet and pipe the results to the Format-List<\/b> to display the newly added description<\/b>.<\/i><\/span><\/span><\/p>\n

\"Image<\/a><\/span><\/p>\n

Okay, enough theory. I want to create aliases for all of the functions exposed by my HSGWMImoduleV5<\/b> (I will add the aliases and the function descriptions in HSGWMImoduleV6<\/b>). 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<\/b> cmdlet to retrieve the functions. These two commands and their associated output are shown here:<\/span><\/p>\n

\n

PS C:\\Users\\ed.IAMMRED> Import-Module hsg*5<\/span><\/span><\/p>\n

PS C:\\Users\\ed.IAMMRED> Get-Command -Module hsg*5<\/span><\/span><\/p>\n

 <\/span><\/span><\/p>\n

CommandType<\/span>  <\/span>            <\/span>Name<\/span>   <\/span>            <\/span>            <\/span>            <\/span>Definition<\/span><\/span><\/span><\/span><\/p>\n

Function            <\/span>            <\/span>Get-WmiClassesAndQuery           <\/span>…<\/span><\/span><\/p>\n

Function            <\/span>            <\/span>Get-WMIClassesWithQualifiers     <\/span>…<\/span><\/span><\/p>\n

Function            <\/span>            <\/span>Get-WmiClassMethods    <\/span>            <\/span>…<\/span><\/span><\/p>\n

Function            <\/span>            <\/span>Get-WmiClassProperties  <\/span>            <\/span>…<\/span><\/span><\/p>\n

Function            <\/span>            <\/span>Get-WmiKey      <\/span>            <\/span>            <\/span>…<\/span><\/span><\/p>\n

Function            <\/span>            <\/span>Get-WmiKeyvalue           <\/span>            <\/span>…<\/span><\/span><\/p>\n

Filter     <\/span>            <\/span>            <\/span>HasWmiValue    <\/span>            <\/span>            <\/span>…<\/span><\/span><\/p>\n

Function            <\/span>            <\/span>New-Underline  <\/span>            <\/span>            <\/span>…<\/span><\/span><\/p>\n

Function            <\/span>            <\/span>Out-TempFile     <\/span>            <\/span>            <\/span>begin {…<\/span><\/span><\/p>\n<\/p>\n<\/blockquote>\n

One thing that makes it easier to add the aliases and the function descriptions is to load the HSGWMImoduleV5<\/b> via the Import-Module<\/b> 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. <\/span><\/p>\n

After the changes are made to the new HSGWMImoduleV6<\/b>, I save it to my working directory. Next, I remove the HSGWMImoduleV5<\/b> from memory by using the Remove-Module<\/b> cmdlet as shown here:<\/span><\/p>\n

\n

Remove-Module hsg*<\/span><\/p>\n<\/blockquote>\n

I peruse the function: drive<\/b> to ensure that all of my WMI functions successfully unloaded. To do this, I use dir<\/b> command (alias for the Get-Childitem<\/b> cmdlet) on the function drive. This command is shown here:<\/span><\/p>\n

\n

dir function:<\/span><\/p>\n<\/blockquote>\n

Now I import my newly revised HSGWMImoduleV6<\/b>. <\/span><\/p>\n

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<\/b> by piping it to Get-Member<\/b>. This command is shown in the following figure.<\/span><\/p>\n

\"Image<\/a><\/span><\/p>\n

By adding the two attributes, I can use Get-Help<\/b> to filter out my functions. First, I can filter out all of my functions by using Get-Help<\/b>:<\/span><\/p>\n

\n

Get-Help * | ? {$_.role}<\/span><\/p>\n<\/blockquote>\n

To find only the functions that work with WMI metadata, I use the value meta<\/b> in the syntax that is shown here:<\/span><\/p>\n

\n

Get-Help * | ? {$_.role -match ‘meta’}<\/span><\/p>\n<\/blockquote>\n

To find the helper functions, I use the value helper<\/b> <\/i>in the following command:<\/span><\/p>\n

\n

Get-Help * | ? {$_.role -match ‘helper’}<\/span><\/p>\n<\/blockquote>\n

To find the query commands, I use this query:<\/span><\/p>\n

\n

Get-Help * | ? {$_.role -match ‘query’}<\/span><\/p>\n<\/blockquote>\n

The commands and associated output are shown in the following figure.<\/span><\/p>\n

\"Image<\/a><\/span><\/p>\n

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:<\/span><\/p>\n

\n

.Role<\/span><\/p>\n

Meta<\/span><\/p>\n

.Component<\/span><\/p>\n

HSGWMIModuleV6<\/span><\/p>\n<\/blockquote>\n

I placed these beneath the parameter<\/b> <\/i>section and above the notes<\/b> <\/i>section. This is shown in the following figure.<\/span><\/p>\n

\"Image<\/a><\/span><\/p>\n

I created aliases for all the commands in the module. To find all the aliases, use this command:<\/span><\/p>\n

\n

Get-Command -Module hsg*6 -CommandType function | % {Get-Alias -Definition $_.name}<\/span><\/p>\n<\/p>\n<\/blockquote>\n

That’s it for my WMI Helper module. I have uploaded version 6 to the <\/span>Scripting Guys Script Repository<\/span><\/a>. If there are other things you would like to see in my module, let me know via email at <\/span>scripter@microsoft.com<\/span><\/a>.<\/span><\/span><\/p>\n

WMI Week will continue tomorrow when I will talk about an easy way to use WMI association classes. <\/span><\/p>\n

I invite you to follow me on <\/span>Twitter<\/span><\/a> and <\/span>Facebook<\/span><\/a>. If you have any questions, send email to me at <\/span>scripter@microsoft.com<\/span><\/a>, or post your questions on the <\/span>Official Scripting Guys Forum<\/span><\/a>. See you tomorrow. Until then, peace.<\/span><\/span><\/p>\n<\/p>\n

Ed Wilson, Microsoft Scripting Guy<\/span><\/b><\/span><\/p>\n<\/p>\n

 <\/span><\/strong><\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

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 […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[52,3,4,45,6],"class_list":["post-12251","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-modules","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell","tag-wmi"],"acf":[],"blog_post_summary":"

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 […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/12251","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=12251"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/12251\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=12251"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=12251"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=12251"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}