{"id":13801,"date":"2011-05-28T00:01:00","date_gmt":"2011-05-28T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/05\/28\/learn-how-to-use-description-attributes-in-powershell-functions\/"},"modified":"2011-05-28T00:01:00","modified_gmt":"2011-05-28T00:01:00","slug":"learn-how-to-use-description-attributes-in-powershell-functions","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/learn-how-to-use-description-attributes-in-powershell-functions\/","title":{"rendered":"Learn How to Use Description Attributes in PowerShell Functions"},"content":{"rendered":"

Summary<\/b>: Microsoft Scripting Guy, Ed Wilson, teaches you how to use description attributes to enable a quick retrieval of Windows PowerShell functions.<\/p>\n

Weekend Scripter <\/h3>\n

Microsoft Scripting Guy, Ed Wilson, is here. Well, the 2011 Scripting Games are nearly completely over. “What?” you may ask. “Is there more to come?” Not specifically. But the impact of the 2011 Scripting Games will continue to be felt for the rest of the year. Common problems that Scripting Games participants had will continue to be addressed in future Hey, Scripting Guy! blogs, in conference presentations, and in feedback to other Windows PowerShell writers at Microsoft. <\/p>\n

But today, I am not going to write about the 2011 Scripting Games. Instead I want to talk about something that is simply cool. You will need to decide how you want to use the information. That is right—I have a solution that is searching for a problem to solve. I got the idea while reading Windows PowerShell Cookbook<\/i> by Lee Holmes.<\/p>\n

As I was searching for a problem, I initially thought that I could use my solution to identify functions as coming from specific modules. This was something that if I knew about previously, I had forgotten; and therefore, I thought my solution would be a cool approach. However, before I expend much effort on a task, I generally like to see what capabilities Windows PowerShell exposes. <\/p>\n

As it turns out, you can easily find commands that are exported from a module by using the Get-Module<\/b> cmdlet. I then use the Select-Object<\/b> cmdlet to expand the exportedCommands <\/b>property. The reason for this, is that without using the ExpandProperty <\/i>parameter, it is difficult to see all of the commands that are actually exported. This is illustrated by the following series, where I try a variety of commands to expand the ExportedCommands<\/b> property.<\/p>\n

\n

PS C:\\Users\\ed.NWTRADERS> Get-Module conv* | Select-Object exportedCommands<\/span><\/span><\/span><\/p>\n

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

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

—————-                      <\/span><\/span>                                                                                                                                                                                                     <\/span><\/span><\/span><\/span><\/span><\/p>\n

{ConvertTo-Feet, ConvertTo-Miles, ConvertTo-MetersPerSecond, ConvertTo-Pounds…}<\/span>                                                                                                                                                          <\/span><\/span><\/span><\/span><\/span><\/p>\n

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

PS C:\\Users\\ed.NWTRADERS> Get-Module conv* | Select-Object exportedCommands | fl *<\/span><\/span><\/span><\/p>\n

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

ExportedCommands : {ConvertTo-Feet, ConvertTo-Miles, ConvertTo-MetersPerSecond, ConvertTo-Pounds…}<\/span><\/span><\/span><\/p>\n

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

PS C:\\Users\\ed.NWTRADERS> Get-Module conv* | Select-Object exportedCommands | ft *<\/span><\/span><\/span><\/p>\n

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

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

—————-                                                                   <\/span><\/span>                                                                                                                                                        <\/span><\/span><\/span><\/span><\/span><\/p>\n

{ConvertTo-Feet, ConvertTo-Miles, ConvertTo-MetersPerSecond, ConvertTo-Pounds…}                      <\/span><\/span>                                                                                                                                    <\/span><\/span><\/span><\/span><\/span><\/p>\n

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

PS C:\\Users\\ed.NWTRADERS> Get-Module conv* | Select-Object exportedCommands | fw *<\/span><\/span><\/span><\/p>\n

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

{ConvertTo-Feet, ConvertTo-Miles, ConvertTo-MetersPerSecond, ConvertTo-Pounds…}<\/span><\/span><\/span>  <\/span><\/span><\/span><\/span><\/span><\/p>\n<\/blockquote>\n

The following command shows the use of the ExpandProperty <\/i>parameter. Note that I am using Get-Module<\/b> to retrieve the conversion module<\/a> that I wrote in the first six Weekend Scripter blogs<\/a>. The complete conversion module<\/a> is available on the Scripting Guys Script Repository.<\/p>\n

\n

PS C:\\Users\\ed.NWTRADERS> Get-Module conv* | select-object -ExpandProperty exportedCommands<\/span><\/span><\/span><\/p>\n

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

Name                           <\/span>Value<\/span>           <\/span><\/span><\/span><\/span><\/span><\/p>\n

—-                           <\/span>—–<\/span>            <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-Feet                 <\/span>ConvertTo-Feet   <\/span><\/span>      <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-Miles                <\/span>ConvertTo-Miles   <\/span>  <\/span>  <\/span><\/span>   <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-MetersPerSecond      <\/span>ConvertTo-MetersPerSecond   <\/span>  <\/span><\/span> <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-Pounds               <\/span>ConvertTo-Pounds  <\/span>  <\/span><\/span>    <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-Meters               <\/span>ConvertTo-Meters    <\/span>  <\/span><\/span>  <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-celsius              <\/span>ConvertTo-celsius    <\/span> <\/span><\/span>  <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-Fahrenheit           <\/span>ConvertTo-Fahrenheit    <\/span><\/span>  <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-Liters               <\/span>ConvertTo-Liters   <\/span> <\/span><\/span>   <\/span><\/span><\/span><\/span><\/span><\/p>\n

ConvertTo-Kilometers           <\/span>ConvertTo-Kilometers   <\/span><\/span>   <\/span><\/span><\/span><\/span><\/span><\/p>\n<\/blockquote>\n

Therefore, as it turns out, using the comment<\/b> attribute does not “buy me anything” for identifying functions as coming from a module. But what about a higher level of abstraction? My Windows PowerShell ISE profile loads a specific module and several functions that are contained in separate files. This is shown in the following image.<\/p>\n

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

Although I can use the Get-Module<\/b> cmdlet to retrieve functions that are exported from my Windows PowerShell ISE profile module, I will not be able to retrieve the functions that are contained in other files. To rectify this, I can use my “solution in search of a problem” comment attribute technique. <\/p>\n

For example, I have no information that tells me that the Get-UsGovWeather<\/b> function (created in the Get-UsGovWeatherFunction.ps1 script) is loaded via my profile. If I use Get-Item<\/b> to retrieve information about that function, the only hint might be that it comes from the iseProfileFileModule folder. This is shown in the following image.<\/p>\n

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

Therefore, the solution is to add a description attribute to the Get-UsGovWeather<\/b> function. This is shown here:<\/p>\n

\n

[System.ComponentModel.Description(“Loaded via Profile”)]<\/span><\/span><\/span><\/p>\n<\/blockquote>\n

To retrieve this information, I access the attributes<\/b> property from the ScriptBlock<\/b> object. One way to do this is shown here:<\/p>\n

\n

PS C:\\Users\\ed.NWTRADERS> (Get-Command Get-UsGovWeather).Scriptblock.attributes<\/span><\/span><\/span><\/p>\n

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

Description                                       <\/span>       <\/span>TypeId   <\/span><\/span>      <\/span><\/span><\/span><\/span><\/span><\/p>\n

———–                                              <\/span>——<\/span>     <\/span><\/span><\/span><\/span><\/span><\/p>\n

Loaded via Profile                                       <\/span>System.ComponentModel.DescriptionAttribute<\/span>          <\/span><\/span><\/span><\/span><\/span><\/p>\n<\/blockquote>\n

When I add the Description<\/b> attribute to a function, it needs to be the first line after the function declaration. This is shown here:<\/p>\n

\n

Function Get-UsGovWeather<\/span><\/span><\/span><\/p>\n

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

 <\/span><\/span>[System.ComponentMOdel.Description(“Loaded via Profile”)]<\/span><\/span><\/span><\/span><\/p>\n

 <\/span><\/span>Param([string]$zip,<\/span><\/span><\/span><\/span><\/p>\n

       <\/span><\/span>[int]$numberDays<\/span><\/span><\/span><\/span><\/p>\n

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

You can see that this appears even before the Param<\/b> statement. One thing that I have not been able to do is to integrate this with comment-based Help. If I place the command before the comment-based Help, as shown here, an error occurs. <\/p>\n

\n

function Save-AllISEFiles<\/span><\/span><\/span><\/p>\n

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

 <\/span><\/span>[System.ComponentMOdel.Description(“Loaded via Profile”)]<\/span><\/span><\/span><\/span><\/p>\n

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

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

     <\/span><\/span>Saves all ISE Files except for untitled files. If You have<\/span><\/span><\/span><\/span><\/p>\n<\/blockquote>\n

The error message from the previous command is shown here:<\/p>\n

\n

Unexpected attribute ‘System.ComponentMOdel.Description’.<\/span><\/span><\/span><\/p>\n<\/blockquote>\n

\n

At C:\\Users\\ed.NWTRADERS\\documents\\WindowsPowerShell\\Modules\\iseProfileModule\\Save-AllIseFiles.ps1:3 char:36<\/span><\/span><\/span><\/p>\n

+  <\/span>[System.ComponentMOdel.Description <<<< (“Loaded via Profile”)]<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>+ CategoryInfo          <\/span>: ParserError: (:) [], ParseException<\/span><\/span><\/span><\/span><\/p>\n

    <\/span><\/span>+ FullyQualifiedErrorId : UnexpectedAttribute<\/span><\/span><\/span><\/span><\/p>\n<\/blockquote>\n

Depending on where I place the command, the script seems to alternate from ignoring the command or generating an error. It might not be possible to combine this technique with a function that uses comment-based Help. <\/p>\n

To retrieve all of the descriptions, you can use code such as the Get-FunctionAttributes<\/b> script, as shown here: <\/p>\n

\n

Get-FunctionAttributes.ps1<\/b><\/p>\n<\/blockquote>\n

\n

foreach( $function in (Get-Command -CommandType function))<\/span><\/span><\/span><\/p>\n

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

 <\/span><\/span>if($function.scriptblock.attributes[0].description)<\/span><\/span><\/span><\/span><\/p>\n

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

    <\/span><\/span>write-host $function.Name $function.scriptblock.attributes[0].description<\/span><\/span><\/span><\/span><\/p>\n

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

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

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

Ed Wilson, Microsoft Scripting Guy<\/b><\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Microsoft Scripting Guy, Ed Wilson, teaches you how to use description attributes to enable a quick retrieval of Windows PowerShell functions. Weekend Scripter Microsoft Scripting Guy, Ed Wilson, is here. Well, the 2011 Scripting Games are nearly completely over. “What?” you may ask. “Is there more to come?” Not specifically. But the impact of […]<\/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":[69,3,4,61,45,77],"class_list":["post-13801","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-functions","tag-scripting-guy","tag-scripting-techniques","tag-weekend-scripter","tag-windows-powershell","tag-writing"],"acf":[],"blog_post_summary":"

Summary: Microsoft Scripting Guy, Ed Wilson, teaches you how to use description attributes to enable a quick retrieval of Windows PowerShell functions. Weekend Scripter Microsoft Scripting Guy, Ed Wilson, is here. Well, the 2011 Scripting Games are nearly completely over. “What?” you may ask. “Is there more to come?” Not specifically. But the impact of […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/13801","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=13801"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/13801\/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=13801"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=13801"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=13801"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}