How to integrate its PowerShell scripts help? [Quick Guide]

7:49 pm March 27, 20176573

I. introduction

when we film with script PowerShell , it is not uncommon to use the commandlet “ Get-Help ” or its alias “ Help ” to get help on the use of a commandlet precisely. When considering to broadcast a script on GitHub for example as I have lately, interestingly on the one hand to encode it properly, but also to include aid within its script.

How are you going to tell me? That’s what we’ll see in this tutorial and it is unknowingly, you already produce this aid.

All of my scripts published on GitHub incorporates assistance available directly from the PowerShell console, here’s the passage access to my scripts: GitHub

II. Syntax for help

in fact, there are two methods to provide assistance with its scripts or directly within the file. Ps1 in your script, either within an external XML file that respects the MMAH syntax ( Microsoft Assistance Markup Language ). For my part, to this day I use only the internal method to the script that we will see in this script, the XML method, I direct you to this article in the first place: MSDN – Help XML

internal method to the script is based on your comments, and mainly on the block of comments that we usually include at the beginning of the script. As a reminder, in PowerShell a block comment how by “<#" et se termine par "#>“.

Inside this block, we’ll indicate different predefined keywords and Get-Help can interpret. Among which:

. SYNOPSIS. DESCRIPTION. PARAMETER . PARAMETER . EXAMPLE. INPUTS. OUTPUTS. NOTES 

the preceding keyword is important in the syntax of your help. In structure it is very simple, just add the associated description as a result of each key word (or on the lines below).

For the keyword “ PARAMETER ” which allows to declare the parameters of your script, use an iteration of the keyword parameter, specifying the name of the parameter and its purpose. Use the same principle for the examples.

You can include help within your functions on the same principle, namely a block comment-based help. This block of comment for aid may be included at the beginning or the end of the function.

Note: If in your script, the comment block corresponding to the overall assistance of the script is followed by the declaration of a function, the help will be associated with this function. So help is associated with the script, he must leave two blank lines between the end of the comment block and the declaration of the function.

III. Example

if I take one of my creations, example here is the block I’ve included aid:

 <#
.SYNOPSIS
    This script geolocation one or several IP address by a web request on the website geoipview.com

.DESCRIPTION
    Specify a list of IP address that you want to geolocation, and the function return the city and the country (origin) of the IP.

.PARAMETER IPToCheck
    The list of IP address, it's a required parameter.

.EXAMPLE
    .Get-IPLocation -IPToCheck "4.4.4.4","8.8.8.8"
    Get the location of two IP address : 4.4.4.4 and 8.8.8.8

.INPUTS

.OUTPUTS
    
.NOTES
    NAME:    Get-IPLocation.ps1
    AUTHOR:    Florian Burnel
    EMAIL:   [email protected]
    WWW:    www.it-connect.fr
    Twitter:@FlorianBurnel

    VERSION HISTORY:

    1.0     2017.01.17
            Initial Version

#> 

then from a PowerShell console, if you execute the command “ help.Get-IPLocation.ps1” where “ Get – IPLocation.ps1 ” is the name of my script, so we get this in return:

 PS C:UsersFlorianDocumentsGitHubPowerShellNETWORK-Get-IPLocation > help.Get-IPLocation.ps1 name C:UsersFlorianDocumentsGitHubPowerShellNETWORK-Get-IPLocationGet-IPLocation.ps1 summary
    [ThisscriptonegeolocationhoweverseveralIPaddressesbyawebrequestonthewebsitegeoipviewcomsyntaxC:UsersFlorianDocumentsGitHubPowerShellNETWORK-Get-IPLocationGet-IPLocationps1[[-IPToCheck] ] [] DESCRIPTION Specify a list of IP addresses that you want to geolocation, and the function return the city and the country (origin) of the IP.

RELATED links comments to view examples, type: "get-help C:UsersFlorianDocumentsGitHubPowerShellNETWORK-Get-IPLocationGet-IPLocation.ps1 - examples".
    For more information, type: "get-help C:UsersFlorianDocumentsGitHubPowerShellNETWORK-Get-IPLocationGet-IPLocation.ps1 - detailed".
    For technical information, type: "get-help C:UsersFlorianDocumentsGitHubPowerShellNETWORK-Get-IPLocationGet-IPLocation.ps1 - full". 

Which gives an image:

in the same way, if you run “ help.Get-IPLocation.ps1 – Full ” to get complete help, it should be noted that aid is returned entirely with description of the parameters of the entry, of the output as well as the notes. Which was not the case with the basic help that returns only what might be called the presentation of the script.

You can get more information on the blocks to help via this command:

 help about_comment_based_help 

… Or this page: About_Comment_Based_Help

Finally, I’ll be back to finish on using outsourced with an XML file, there is a nice editor published on CodePlex to create easier assistance based on this method, it’s Editor Help Cmdlet.

I hope that this tutorial will allow you to progress in your scripting and it will allow you to integrate assistance worthy of the name associated with your work, this will facilitate the use of your code by a third person.