Skip to main content

How to enable Get-Help with your functions in PowerShell

PowerShell has a very robust online help capabilities.  These abilities are extended to you, the user, when you are creating functions and scripts.  You may have functions that you load as part of your profile or that you have created as part of a customized module.  To do this is very simple.  Take a look at the function below.
Function WriteText {
Param (
    [parameter(Mandatory=$True,ValueFromPipeline=$True)]$InputValue `
    = (Read-Host 'Please provide an input value: '))
BEGIN {}
PROCESS{
    Write-Host $InputValue
    }
END {}
}

This function simply outputs what you put into it.  Let’s add some help functionality to it. 

To do this, we need to add a block comment section immediately after the Function declaration line.  Block comments are normal comment statements.  The difference is that instead of every line starting with ‘#’, we start with ‘<#’.  You can type as many lines as you want and all of them will be considered comments until you end the comment block with ‘#>’.

We add the help by adding these lines.
.SYNOPSIS
Provides a brief statement of what this function or script does.
.DESCRIPTION
This is a more detailed explaination of the script or function.
.PARAMETER parameter
This will descript the purpose of each parameter.  Add addition .PARAMTER lines for multiple parameters
.EXAMPLE
Provide one or more examples by adding more .EXAMPLE lines.
.INPUTS
This is the list of Microsoft .NET Framework objects that can be piped to this function.
.OUTPUTS
The .NET Framework type of object that is returned from this function or cmdlet.
.NOTES
Any additional information about this function or cmdlet.

You can read about these, and more attributes of the help file by executing this line in PowerShell: help About_ comment_based_help

Let’s add a help file and see the results.

Function WriteText {
<#
.SYNOPSIS
Writes what you give it.
.DESCRIPTION
This function displays the input that it was provided.
.PARAMETER $InputValue
Accepts String or integer values.
.EXAMPLE
WriteText "Hello World"
.EXAMPLE
WriteText -InputValue "Hello World"
#>
Param (
    [parameter(Mandatory=$True,ValueFromPipeline=$True)]$InputValue `
    = (Read-Host 'Please provide an input value: '))
BEGIN {}
PROCESS{

    Write-Host $InputValue
    }
END {}
}

Here is the help file if we execute Get-Help WriteText –Full
NAME
    WriteText
   
SYNOPSIS
    Writes what you give it.
   
SYNTAX
    WriteText [-InputValue] <Object> [<CommonParameters>]
   
   
DESCRIPTION
    This function displays the input that it was provided.
   

PARAMETERS
    -InputValue <Object>
       
        Required?                    true
        Position?                    1
        Default value               
        Accept pipeline input?       true (ByValue)
        Accept wildcard characters? 
       
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        "get-help about_commonparameters".
   
INPUTS
   
OUTPUTS
   
    -------------------------- EXAMPLE 1 --------------------------
   
    C:\PS>WriteText "Hello World"

   -------------------------- EXAMPLE 2 --------------------------
   
    C:\PS>WriteText -InputValue "Hello World"

  
RELATED LINKS

Comments

Popular posts from this blog

Adding a Comment to a GPO with PowerShell

As I'm writing this article, I'm also writing a customization for a PowerShell course I'm teaching next week in Phoenix.  This customization deals with Group Policy and PowerShell.  For those of you who attend my classes may already know this, but I sit their and try to ask the questions to myself that others may ask as I present the material.  I finished up my customization a few hours ago and then I realized that I did not add in how to put a comment on a GPO.  This is a feature that many Group Policy Administrators may not be aware of. This past summer I attended a presentation at TechEd on Group Policy.  One organization in the crowd had over 5,000 Group Policies.  In an environment like that, the comment section can be priceless.  I always like to write in the comment section why I created the policy so I know its purpose next week after I've completed 50 other tasks and can't remember what I did 5 minutes ago. In the Group Policy module for PowerShell V3, th

Return duplicate values from a collection with PowerShell

If you have a collection of objects and you want to remove any duplicate items, it is fairly simple. # Create a collection with duplicate values $Set1 = 1 , 1 , 2 , 2 , 3 , 4 , 5 , 6 , 7 , 1 , 2   # Remove the duplicate values. $Set1 | Select-Object -Unique 1 2 3 4 5 6 7 What if you want only the duplicate values and nothing else? # Create a collection with duplicate values $Set1 = 1 , 1 , 2 , 2 , 3 , 4 , 5 , 6 , 7 , 1 , 2   #Create a second collection with duplicate values removed. $Set2 = $Set1 | Select-Object -Unique   # Return only the duplicate values. ( Compare-Object -ReferenceObject $Set2 -DifferenceObject $Set1 ) . InputObject | Select-Object – Unique 1 2 This works with objects as well as numbers.  The first command creates a collection with 2 duplicates of both 1 and 2.   The second command creates another collection with the duplicates filtered out.  The Compare-Object cmdlet will first find items that are diffe

How to list all the AD LDS instances on a server

AD LDS allows you to provide directory services to applications that are free of the confines of Active Directory.  To list all the AD LDS instances on a server, follow this procedure: Log into the server in question Open a command prompt. Type dsdbutil and press Enter Type List Instances and press Enter . You will receive a list of the instance name, both the LDAP and SSL port numbers, the location of the database, and its status.