{"id":17151,"date":"2010-09-11T00:01:00","date_gmt":"2010-09-11T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2010\/09\/11\/automatically-add-comment-based-help-to-your-powershell-scripts\/"},"modified":"2010-09-11T00:01:00","modified_gmt":"2010-09-11T00:01:00","slug":"automatically-add-comment-based-help-to-your-powershell-scripts","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/automatically-add-comment-based-help-to-your-powershell-scripts\/","title":{"rendered":"Automatically Add Comment-Based Help to Your PowerShell Scripts"},"content":{"rendered":"

Summary<\/strong>: Automatically add comment-based help to your Windows PowerShell scripts; learn how in this how-to article by Scripting Guy Ed Wilson.<\/p>\n

 <\/p>\n

Microsoft Scripting Guy Ed Wilson here. Last Sunday, I spent the morning creating a Windows PowerShell ISE profile<\/a>. Today, I thought I would add something to that profile that will make my life easier. When I was creating the conversion module back in the series of articles I wrote about creating and using modules<\/a>, I created a text file that I called my help template<\/a>. When I wish to add comment-based help to a script or to a function, I have to do the following:<\/p>\n

    \n
  1. Use search to locate the help text file.<\/li>\n
  2. Open the help text file in Notepad.<\/li>\n
  3. Copy the text of the file to the clipboard.<\/li>\n
  4. Switch to the Windows PowerShell ISE.<\/li>\n
  5. Paste the contents of the clipboard to the script or function that is under development.<\/li>\n
  6. Switch back to Notepad.<\/li>\n
  7. Close the help text file.<\/li>\n
  8. Close the Windows Search results Explorer pane.<\/li>\n
  9. Switch back to the Windows PowerShell ISE.<\/li>\n
  10. Edit the comment-based text in the Windows PowerShell ISE.<\/li>\n
  11. Add the current date to the last edit field of the comment.<\/li>\n<\/ol>\n

    Granted, it does not take a long time to perform these 11 steps, but it is a lot of mousing and typing, and it does take several minutes to complete. As a result, I do not add comment-based help to my scripts or functions as often as I should. <\/p>\n

    Now that I have a Windows PowerShell ISE profile, it makes sense to add a function to automatically add comment-based help to my Windows PowerShell scripts and functions. The function is called Add-Help and is shown here. <\/p>\n

    \n

    Add-Help<\/strong><\/p>\n

    Function<\/span> <\/span>Add-Help<\/span>
    <\/span>{<\/span>
     <\/span>$helpText<\/span> <\/span>=<\/span> <\/span>@<\/span>”
    <#
       .Synopsis
        This does that 
       .Example
        Example-
        Example- accomplishes 
       .Parameter 
        The parameter
       .Notes
        NAME: Example-
        AUTHOR: $env:username
        LASTEDIT: $(Get-Date)
        KEYWORDS:
       .Link
        Http:\/\/www.ScriptingGuys.com
    #Requires -Version 2.0
    #>
    “<\/span>@<\/span>
     <\/span>$psise<\/span>.CurrentFile.Editor.InsertText(<\/span>$helpText<\/span>)<\/span>
    <\/span>}<\/span> <\/span>#<\/span>end<\/span> <\/span>function<\/span> <\/span>add-help<\/span> <\/p>\n<\/blockquote>\n

    The first thing I do in the Add-Help<\/strong> function is create a here-string<\/strong>. The here-string<\/strong> allows me to not worry about quoting rules or other coding conventions. Everything between the @”<\/strong> and the “@ <\/strong>symbols is interpreted as a string. Just as there are two kinds of regular strings—literal and expanding—so too are there two kinds of here-strings<\/strong>, literal and expanding. I am using the expanding here-string<\/strong> so that I can get the date to update. In addition, the username is pulled from the environmental username<\/strong> variable. If you do not want to use the environmental username<\/strong> variable for your script user name, you can hard code this value (this is in fact what I do in my personal Windows PowerShell ISE profile). <\/p>\n

    Beyond the expanding here-string<\/strong>, the only really interesting thing about the function is the line of code that inserts text (obviously, this takes place at the current insertion point). To do this, I use the InsertText<\/strong> method from the Editor<\/strong> object from the CurrentFile<\/strong> object. This code is shown here:<\/p>\n

    \n
    $psise<\/span>.CurrentFile.Editor.InsertText(<\/span>$helpText<\/span>)<\/span> <\/div>\n<\/blockquote>\n

    To add the Add-Help<\/strong> function to my Windows PowerShell ISE profile, I use the Set-Profile<\/strong> function I created last Sunday. It opens my profile in the Windows PowerShell ISE. Next I simply paste the function in the profile as shown in the following image.<\/p>\n

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

    After I have saved the Windows PowerShell ISE profile, and closed and reopened the Windows PowerShell ISE. I now place my insertion point to the first line under the opening brace (curly bracket) of the Add-Help<\/strong> function, and I use the Add-Help<\/strong> function to add help to my Add-Help<\/strong> function. This is shown in the following image.<\/p>\n

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

    One thing to keep in mind is that by default, my Add-Help<\/strong> function adds the .Parameter<\/strong> comment. If you do not have any parameters, or if you do not use this comment properly, your help will not work with the Get-Help<\/strong> cmdlet. If you do not intend to use this comment, delete it before adding the Add-Help<\/strong> function to your profile. <\/p>\n

     <\/p>\n

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

     <\/p>\n

    Ed Wilson and Craig Liebendorfer, Scripting Guys<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"

    Summary: Automatically add comment-based help to your Windows PowerShell scripts; learn how in this how-to article by Scripting Guy Ed Wilson.   Microsoft Scripting Guy Ed Wilson here. Last Sunday, I spent the morning creating a Windows PowerShell ISE profile. Today, I thought I would add something to that profile that will make my life […]<\/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":[3,4,61,45,100],"class_list":["post-17151","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-scripting-guy","tag-scripting-techniques","tag-weekend-scripter","tag-windows-powershell","tag-windows-powershell-ise"],"acf":[],"blog_post_summary":"

    Summary: Automatically add comment-based help to your Windows PowerShell scripts; learn how in this how-to article by Scripting Guy Ed Wilson.   Microsoft Scripting Guy Ed Wilson here. Last Sunday, I spent the morning creating a Windows PowerShell ISE profile. Today, I thought I would add something to that profile that will make my life […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/17151","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=17151"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/17151\/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=17151"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=17151"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=17151"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}