Powershell: Function with Comment-Based Help

In this scenario I want to prepare generic functionality for preparing query parameters string for uri that can be used later for webrequests etc.

It is a good idea to create description that will allow other users to use Get-Help command with your function or just to read it directly in source file.

You can find much more about creating functions here:

https://docs.microsoft.com/en-us/powershell/scripting/learn/ps101/09-functions

So… Lets create a function with description section

function Get-UriQueryParams{
    <# 
           This is description section.
    #>
 }

Important thing is that Get-Help command can return description in three ways: basic (default), detailed and full. For now I want to prepare basic version and for that I need to prepare SYNOPSIS and DESCRIPTION sections.

function Get-UriQueryParams{
    <#

    .SYNOPSIS
    Returns prepared query parameters strings for Uri.

    .DESCRIPTION
    The `Get-UriQueryParams` function returns prepared query parameters strings.

    #>
 }

Get-Help Get-UriQueryParams

As you can see some sections are generated automatically and there is no need to write everything manually.

Now I will define parameters that can be passed to function.

function Get-UriQueryParams{
    <#

    .SYNOPSIS
    Returns prepared query parameters strings for Uri.

    .DESCRIPTION
    The `Get-UriQueryParams` function returns prepared query parameters strings.

    #>
    param(
        [int]$Param1
        ,[int[]]$Param2
        ,[string]$Param3
        ,[string[]]$Param4
        ,[ValidateSet('true','false')][string]$Param5
    )
 }

Get-Help Get-UriQueryParams

Now SYNTAX section will be modified with defined parameters.

I usually create EXAMPLE sections when function have final state and executes every scenario properly.

function Get-UriQueryParams{
    <#

    .SYNOPSIS
    Returns prepared query parameters strings for Uri.

    .DESCRIPTION
    The `Get-UriQueryParams` function returns prepared query parameters strings.

    #>
    param(
        [int]$Param1
        ,[int[]]$Param2
        ,[string]$Param3
        ,[string[]]$Param4
        ,[ValidateSet('true','false')][string]$Param5
    )
    # Set Scheme for QueryParams for later use in Uri
    $QueryParams="?"
    
    # check if $Param1 is passed and it is not $null
    if($Param1){
        # add parameter to variable
        $QueryParams+="param1=$Param1&"
    }

    if($Param2){
        # $Param2 is definied as array of integers and 
        # it requires to join every item into string
        # comma separated
        $QueryParams+="param2=$($Param2 -join ",")&"
    }

    if($Param3){
        $QueryParams+="param3=$Param3&"
    }

    if($Param4){
        # $Param4 is defined as array of strings and
        # it requires to join every item into string
        # comma separated
        $QueryParams+="param4=$($Param4 -join ",")&"
    }

    if($Param5){
        $QueryParams+="param5=$Param5&"
    }

    # if none parameter was passed set $QueryParameter to null
    # else remove last character from it for remove '&' character
    # from last passed parameter
    if($QueryParams -eq '?'){
        $QueryParams=$null
    }else{
        $QueryParams=$QueryParams.Substring(0, $QueryParams.Length - 1 )
    }

    # return prepared string
    return $QueryParams
}
Get-Help Get-UriQueryParams

At this moment I’m ready to add EXAMPLE sections at function description. That sections are not part of basic view of Get-Help command and you need to use -detailed or -full switch parameter at end of the command.

Important things are that first line at EXAMPLE section is always call of the function and each example is auto-numbered.

function Get-UriQueryParams{
    <#

    .SYNOPSIS
    Returns prepared query parameters strings for Uri.

    .DESCRIPTION
    The `Get-UriQueryParams` function returns prepared query parameters strings.

    .EXAMPLE
    Get-UriQueryParams -Param1 1

    Get data with Param1 specified.

    .EXAMPLE
    Get-UriQueryParams -Param2 21,22,23 

    Get data with Param2 specified.
        
    .EXAMPLE
    Get-UriQueryParams -Param3 "test_string_param3"

    Get data with Param3 specified.

    .EXAMPLE
    Get-UriQueryParams -Param4 "test_string_param4.1", "test_string_param4.2"

    Get data with Param4 specified.

    .EXAMPLE
    Get-UriQueryParams -Param5 false

    Get data with Param5 specified.

    .EXAMPLE
    Get-UriQueryParams -Param1 1111 -Param5 true

    Get data with Param1 and Param5 specified.

    #>
    param(
        [int]$Param1
        ,[int[]]$Param2
        ,[string]$Param3
        ,[string[]]$Param4
        ,[ValidateSet('true','false')][string]$Param5
    )

    # Set Scheme for QueryParams for later use in Uri
    $QueryParams="?"
    
    # check if $Param1 is passed and it is not $null
    if($Param1){
        # add parameter to variable
        $QueryParams+="param1=$Param1&"
    }

    if($Param2){
        # $Param2 is definied as array of integers and 
        # it requires to join every item into string
        # comma separated
        $QueryParams+="param2=$($Param2 -join ",")&"
    }

    if($Param3){
        $QueryParams+="param3=$Param3&"
    }

    if($Param4){
        # $Param4 is defined as array of strings and
        # it requires to join every item into string
        # comma separated
        $QueryParams+="param4=$($Param4 -join ",")&"
    }

    if($Param5){
        $QueryParams+="param5=$Param5&"
    }

    # if none parameter was passed set $QueryParameter to null
    # else remove last character from it for remove '&' character
    # from last passed parameter
    if($QueryParams -eq '?'){
        $QueryParams=$null
    }else{
        $QueryParams=$QueryParams.Substring(0, $QueryParams.Length - 1 )
    }

    # return prepared string
    return $QueryParams
}

Get-Help Get-UriQueryParams -Detailed

Advertisement

‹ Powershell: Webrequest with Basic Authentication

Powershell: Logging to file ›

Tagged with: Comment-Based Help, CommentsAsPartOfDocumentation, Documentation, Function, Help, Powershell, Uri
Posted in Powershell