Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to enable a PowerShell script to return help text when using Get-Help or -?

Tags:

How do I get my PowerShell script to display help when a user requests help via:

Get-Help -Name myscript.ps1

or

myscript.ps1 -?

For example, to describe my scripts parameters etc.

Updated question

I tried the suggested answers. But I don't see the expected output.

I simply place added the following code to myScript.ps1.

<#
.SYNOPSIS
    A short description of your script.

.DESCRIPTION
    A longer description of your script.

.PARAMETER <-silent>
    First parameter is -silent. It will do Collection Bootstrap silently.  

.PARAMETER <action>
   Second parameter is action. Action could be either bootstrap or join

#>

When I tired

Get-Help .\myScript.ps1

, it shows as follows

NAME
    C:\es\dev\myScript.ps1

SYNOPSIS
    A short description of your script.


SYNTAX
    C:\es\dev\myScript.ps1 [<CommonParameters>]


DESCRIPTION
    A longer description of your script.


RELATED LINKS

REMARKS
    To see the examples, type: "get-help C:\es\dev\myScript.ps1 -examples".
    For more information, type: "get-help C:\es\dev\myScript.ps1 -detailed".
    For technical information, type: "get-help C:\es\dev\myScript.ps1 -full".

I was expecting to see the description of the parameters. I tried both.PARAMETER <-silent> and .PARAMETER -silent. Same results. What is wrong?

Related question update 2 after processing more

I can see the help file after adding parameter section as follows:-

param (

    [Parameter(ParameterSetName='taskJsonFile', Position=1, Mandatory=$true)]
    [String]$taskJsonFile="tasks.json"
)

But very important to see full help file I must use
Get-help .\myscript.ps1 -full Otherwise, it doesn't show full help information.

But here comes my next question. When I tried -full. It shows some irrelevant information. I would like to omit this information to be shown to the user. Now it displays as following:-

NAME C:\es\dev\myscript.ps1

SYNOPSIS It performs Collection Bootstrapping silently or parameterized based.

SYNTAX C:\es\dev\myscript.ps1 [[-action] ] [[-file] ] [[-sasHostname] ] []

DESCRIPTION For silent operation, user has to fill configuration file with desired value at Eurostep.SAS.Collection Bootstrap.Config.psd1. This configuration file has to exist in the same directory of Eurostep.SAS.CollectionBootstrap.ps1 PowerShell script.

PARAMETERS -action

    Required?                    false
    Position?                    2
    Default value                bootstrap
    Accept pipeline input?       false
    Accept wildcard characters?  false

-file <String>

    Required?                    false
    Position?                    3
    Default value                bootstrap_collection.json
    Accept pipeline input?       false
    Accept wildcard characters?  false

-sasHostname <String>

    Required?                    false
    Position?                    4
    Default value                http://localhost:5000
    Accept pipeline input?       false
    Accept wildcard characters?  false

<CommonParameters>
    This cmdlet supports the common parameters: Verbose, Debug,
    ErrorAction, ErrorVariable, WarningAction, WarningVariable,
    OutBuffer, PipelineVariable, and OutVariable. For more information, see
    about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

INPUTS

OUTPUTS

-------------------------- EXAMPLE 1 --------------------------

C:\PS>.\myscript.ps1

For silent Collection Bootstrapping no parameter. It reads values from configuration file myscript.Config.psd1




-------------------------- EXAMPLE 2 --------------------------

C:\PS>.\myscript.ps1 bootstrap bootstrap_collection.json 'http://localhost:5000'

All required parameter provided. Note that hostname must be inside ' '. Because it is a link.

RELATED LINKS

I don't want to show RELATED LINKS INPUTS OUTPUTS , etc.

Is there anyway to remove them from help informtion. Even -Full is used?

like image 588
masiboo Avatar asked Jan 31 '18 15:01

masiboo


People also ask

How do I use get help in PowerShell?

To get help for a PowerShell provider, type Get-Help followed by the provider name. For example, to get help for the Certificate provider, type Get-Help Certificate . You can also type help or man , which displays one screen of text at a time.

What is the result of typing get help * in PowerShell?

The Get-Help cmdlet displays information about Windows PowerShell concepts and commands, including cmdlets, functions, CIM commands, workflows, providers, aliases and scripts. To get help for a Windows PowerShell command, type `Get-Help` followed by the command name, such as: `Get-Help Get-Process`.

How do I add help to a PowerShell script?

To add help to a PowerShell script, type the comment block – <# #>. Then, within the comment block, add the different help keywords. For example, the PowerShell statement below adds the SYNOPSIS, DESCRIPTION and a parameter help information.


1 Answers

The simplest way to do this is to add comment-based help to your script. This is a special comment block that is formatted with specific keywords and then the associated text for those keywords. For example:

<#
.SYNOPSIS
    A short description of your script.

.DESCRIPTION
    A longer description of your script.

.PARAMETER SomeParameter
    A description of the SomeParameter parameter.  

.PARAMETER OtherParameter
    A description of the OtherParameter parameter. Have as many of these lines as you have parameters.

.EXAMPLE
    YourScript.ps1 -SomeParameter 'thing' -OtherParameter 1

    Does something. Have as many examples as you think useful.
#>

These are the keywords I tend to use by default but look at the full list described here for others you might want to include: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1

like image 126
Mark Wragg Avatar answered Sep 19 '22 13:09

Mark Wragg