{"id":3272,"date":"2013-07-06T00:01:00","date_gmt":"2013-07-06T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2013\/07\/06\/weekend-scripter-a-little-powershell-help-here-please\/"},"modified":"2013-07-06T00:01:00","modified_gmt":"2013-07-06T00:01:00","slug":"weekend-scripter-a-little-powershell-help-here-please","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/weekend-scripter-a-little-powershell-help-here-please\/","title":{"rendered":"Weekend Scripter: A Little PowerShell Help Here…Please?"},"content":{"rendered":"

Summary<\/strong>: Guest blogger, Matt Tisdale, talks about adding Help text to Windows PowerShell functions.<\/span>\nMicrosoft Scripting Guy, Ed Wilson, is here. Yesterday I introduced Matt Tisdale as the guest blogger. Guess what? He’s back today!  Dude!! Sweet!!! Here is Matt’s post from yesterday: Optimize Performance of AD DS Queries via PowerShell<\/a>. Today he discusses adding Help text to custom functions…\nI now have a few people at my company who are writing custom Windows PowerShell functions to help other IT team members and business employees. I am very excited to see this, and I always try to provide additional information to help these individuals make functions more beneficial and useful.\nOne of the best ways to make a function useful to others is to add Help text. Anyone who has used Windows PowerShell for more than five minutes is already familiar with the Get-Help<\/strong> cmdlet. If we want to learn how to use the Get-ADUser<\/strong> cmdlet, we simply run Get-Help Get-ADUser -detailed<\/strong>. The information that is displayed by Get-Help<\/strong> appears because the programmer who wrote Get-ADUser<\/strong> added the Help text into their script.\nLikewise, Help text can be added to any custom function quite easily. Let’s say you have a function named Get-FolderData<\/strong>. With just a few lines of script added to the function, other people can run Get-Help Get-FolderData -detailed<\/strong> and see exactly what the function does and how to use it.\nThere are a few ways you can add Help text, but to help maintain a consistent standard at my company, I recommend that everyone use the following standards:<\/p>\n

    \n
  1. Start your Help text block immediately under the first line of script in your function.<\/li>\n
  2. Open your Help text block with the characters <#<\/strong>, and end the block with #><\/strong><\/li>\n
  3. With your Help text, always include SYNOPSIS, DESCRIPTION, and EXAMPLE at a minimum.<\/li>\n<\/ol>\n

    Let’s break this down a little…\nSo what is a Help text block? This is nothing more than a block of script that contains all of the data you want to display when Get-Help<\/strong> is used against your function. Here is a very simple example:<\/p>\n

    Function Get-FolderData() {<\/p>\n

    <#<\/p>\n

    .SYNOPSIS<\/p>\n

    Retrieve specific information about one or more folders<\/p>\n

    .DESCRIPTION<\/p>\n

    This function can be used to read information about folder properties.<\/p>\n

    Some of the properties this function can read include size, when created,<\/p>\n

    last modified and many more.<\/p>\n

    .PARAMETER Path<\/p>\n

    This parameter contains the full path to the folder you wish to<\/p>\n

    display information for.<\/p>\n

    .EXAMPLE<\/p>\n

    Get-FolderData -Path “c:temptest1”<\/p>\n

    This command returns information for the folder c:temptest1<\/p>\n

    #><\/p>\n

    ### CODE GOES HERE ###<\/p>\n

    }\nThat is all it takes. Pretty simple! Notice how the block starts with the characters <#<\/strong> and ends with #><\/strong>? This is my preferred method for building a Help text block. All of the Help text that you want to display simply goes between these two character strings.\nThe next important thing to look for is Keyword headings. Take a look at .SYNOPSIS, .DESCRIPTION, and the other keywords in the previous Help text. Each of these keywords must be entered exactly as shown, including the preceding period. Get-Help<\/strong> looks for these keywords, and they determine how Help data is displayed on the screen.\nMake sure that you always include .SYNOPSIS, .DESCRIPTION, and .EXAMPLE at a minimum. Another keyword that will most likely be used in most of your functions is .PARAMETER. The .PARAMETER and .EXAMPLE keywords can be used as many times as you want.\nInstead of writing a book here about what each of these keywords are used for and all of the other remaining details related to Help text, I recommend that you check out the documentation already provided by Microsoft. To read all of the details about Help text, do either of the following:<\/p>\n