<<< Back to Search

Scripting ::: Parameters ::: Basic declarations

This section present common Parameter declarations that include Optional parameters, Mandatory Parameters, Parameters with inline Help and adding commond default parameters with "CmdletBinding".

Core Snippet

# Scripting ::: Parameters ::: Basic declaration
# PowerShellExamples.com

[CmdletBinding()]
param (

    # Parameter Optional String -_-
    [Parameter()]
    [string]$entryString1,

    # Parameter Mandatory String -_-
    [Parameter(Mandatory=$true)]
    [string]$entryString2,

    # Parameter Mandatory Integer -_-
    #   Validate type on declaration
    [Parameter(Mandatory=$true)]
    [int]$entryInteger1,

    # Parameter with inline Help Message -_-
    #  Help message will be shown when executing typing !?
    [Parameter(Mandatory=$true,HelpMessage="SAMPLE HELP: Type -1 on this example.")]
    [int]$entryIntegerWithHelp2
)
    

Practical Sample

# Scripting ::: Parameters ::: Basic declaration
# PowerShellExamples.com

Function Invoke-TestParameters{

    #[CmdletBinding()]
    # Turns on cmdlet-style parameter binding capabilities, either for a script or for a function
    #   -Add tacitly -Verbose and -Debug parameters 
    #     enabling use Write-Verbose and Write-Debug within the script or function
    #   -Your script or function picks up the other common parameters
    #   -The ability to have -whatif and -confirm added to your script or function.  Declare like this
    #     [CmdletBinding(SupportsShouldProcess=$True,ConfirmImpact=Medium)]. 
    #     and Implement $pscmdlet.ShouldProcess() in your script
    [CmdletBinding()]
    param (

        # Parameter Optional String
        [Parameter()]
        [string]$entryString1,

        # Parameter Mandatory String
        [Parameter(Mandatory=$true)]
        [string]$entryString2,

        # Parameter Mandatory Integer
        #   Validate type on declaration
        [Parameter(Mandatory=$true)]
        [int]$entryInteger1,

        # Parameter with inline Help Message
        #  Help message will be shown when executing typing !?
        [Parameter(Mandatory=$true,HelpMessage="SAMPLE HELP: Type -1 on this example.")]
        [int]$entryIntegerWithHelp2
    )
    Write-Host "`r`nExecuting Invoke-TestParameters" -ForegroundColor Gray
    Write-Host "Entry String 1: $entryString1"
    Write-Host "Entry String 2: $entrystring2"
    Write-Host "Entry Integer 1: $entryInteger1"
    Write-Host "Entry Integer 2: $entryIntegerWithHelp2"
    
    Write-Verbose "This message is only shown because parameter -verbose was passed"
}

Write-Host "Positive test All parameters fullfilled" -ForegroundColor Green
Invoke-TestParameters -entryString1 "String1" -entryString2 "String2" -entryInteger1 10 -entryIntegerWithHelp2 -1

Write-Host "Integer parameter will report error if wrong type was passed" -ForegroundColor Green
Write-Host "Error below is part of the sample" -ForegroundColor Yellow
# using -ErrorAction Continue to allow this script continue after showing the error
Invoke-TestParameters -entryString1 "String1" -entryString2 "String2" -entryInteger1 "abc" -entryIntegerWithHelp2 0 -ErrorAction Continue

Write-Host "Mandatory Parameters if not passed will be asked interactivelly" -ForegroundColor Green
Invoke-TestParameters -ErrorAction Continue

Write-Host "Parameter Help message will be exposed typing !? when entering interactivelly" -ForegroundColor Green
Invoke-TestParameters -entryString1 "String1" -entryString2 "String2" -entryInteger1 1

Write-Host "Showing verbose message by passing parameter -verbose" -ForegroundColor Green
Invoke-TestParameters -entryString1 "String1" -entryString2 "String2" -entryInteger1 10 -entryIntegerWithHelp2 1 -Verbose

Result

PS C:\> & "C:\Users\cesar\Downloads\20210417 PowerShellExamples\Scripting - Parameters - Basic declaration.ps1"
Positive test All parameters fullfilled

Executing Invoke-TestParameters
Entry String 1: String1
Entry String 2: String2
Entry Integer 1: 10
Entry Integer 2: -1
Integer parameter will report error if wrong type was passed
Error below is part of the sample
Invoke-TestParameters : Cannot process argument transformation on parameter 'entryInteger1'. Cannot convert value "abc" to type "System.Int32". Error: "Input string was not in a correct format."
At C:\A2\Proyectos\PowershellExamples\DBScripts\ToDeploy\20210417 PowerShellExamples\Scripting - Parameters - Basic declaration.ps1:50 char:86
+ ... tring1 "String1" -entryString2 "String2" -entryInteger1 "abc" -entryI ...
+                                                             ~~~~~
    + CategoryInfo          : InvalidData: (:) [Invoke-TestParameters], ParameterBindingArgumentTransformationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Invoke-TestParameters
 
Mandatory Parameters if not passed will be asked interactivelly
cmdlet Invoke-TestParameters at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
entryString2: a
entryInteger1: 4
entryIntegerWithHelp2: 5

Executing Invoke-TestParameters
Entry String 1: 
Entry String 2: a
Entry Integer 1: 4
Entry Integer 2: 5
Parameter Help message will be exposed typing !? when entering interactivelly
cmdlet Invoke-TestParameters at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
entryIntegerWithHelp2: !?
SAMPLE HELP: Type -1 on this example.
entryIntegerWithHelp2: -1

Executing Invoke-TestParameters
Entry String 1: String1
Entry String 2: String2
Entry Integer 1: 1
Entry Integer 2: -1
Showing verbose message by passing parameter -verbose

Executing Invoke-TestParameters
Entry String 1: String1
Entry String 2: String2
Entry Integer 1: 10
Entry Integer 2: 1
VERBOSE: This message is only shown because parameter -verbose was passed